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How to Use This Manual 


is manual explains the concepts and terminology of the VAX DATATRIEVE 
tware, also referred to as DATATRIEVE in this manual. It discusses how to 
‘ine domains, records, tables, and procedures and how to catalog them in the 
.X Common Data Dictionary, also referred to simply as CDD. It describes var- 
s ways of managing data stored in RMS files, VAX Rdb/VMS (also referred to 
Rdb), and VAX DBMS (also referred to as DBMS) databases and how to 

rieve information from them. 


tended Audience 


is manual is intended for people who either: 


Have read or done the examples in the VAX DATATRIEVE Handbook 
Have experience using DATATRIEVE-11 | 
Have experience in applications programming 


rou have no prior experience with DATATRIEVE, the VAX DATATRIEVE 
indbook provides information on the basic tasks of managing information with 
.TATRIEVE and can help you get started with DATATRIEVE applications. 
»erating System Information 
verify which versions of your operating system are compatible with this ver- 
1 0f VAX DATATRIEVE, check the most recent copy of the following: 
For the VMS operating system -- VAX/VMS Optional Software Cross 
Reference Table, SPD 25.99.xx 


For the MicroVMS operating system -- MicroVMS Optional Software Cross 
Reference Table, SPD 28.99.xx 
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Structure 


This manual is divided into five major parts, two appendixes, and an index: 


Part 1 


Part 2 


Part 3 


Part 4 


Part 5 


Understanding DATATRIEVE 


Explains basic terminology and concepts of VAX 
DATATRIEVE (Chapter 1). 


Manipulating Data 


Describes how to write record selection expressions, store and 
modify data, and use view domains and hierarchies (Chapters 2 
through 6). 


Programming in DATATRIEVE 


Illustrates programming in DATATRIEVE through use of pro- 
cedures, command files, and variables (Chapters 7 through 9). 


~ Optimizing DATATRIEVE 


Explains how to change record and file definitions, design the 
most efficient records, and improve performance of 
DATATRIEVE applications (Chapters 10 through 12). 


DATATRIEVE and the VAX Information Architecture 


Explains how to use TDMS and FMS forms in a DATATRIEV. 
application, how to access data in DBMS and in Rdb databases 
and how to access remote data (Chapters 13 through 16). 


Appendix A presents a detailed discussion of DATATRIEVE context; Appendix 
lists the sample data definitions created during the DATATRIEVE installation 


procedure. 


Related Manuals 

For other information on the topics covered in this book, see: 
VAX DATATRIEVE Handbook 

VAX DATATRIEVE Guide to Writing Reports 

VAX DATATRIEVE Reference Manual 

VAX DATATRIEVE Guide to Using Graphics 

VAX DATATRIEVE Guide to Programming and Customizing 


VAX Common Data Dictionary Utilities Reference Manual 
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onventions 


nce CDD Version 3.1, CDD path names include a leading underscore. For 
cample: 


R> SHOW DICTIONARY 
e default directory is _CDD$TOP.DTR32.WEAGER 


<amples of output in DATATRIEVE manuals do not reflect this change. You do 
it need to enter CDD path names with the leading underscore. 


mmbols used in examples: 


RET> This symbol tells you to press the RETURN key on the 
keyboard of your terminal. 


TAB> This symbol tells you to press the TAB key on the key- 
board of your terminal. 


CTRL/x> This symbol tells you to press the CTRL (control) key 
and a letter key (Z, C, or Y) at the same time. If you 
press CTRL/Z, the word Exit appears in reverse video; if 
you press CTRL/Y. the word Interrupt appears in 
reverse video. Examples of video output in this book do 
not include either word; instead the conventions “Z and 
“Y are used. 


lor Colored ink in examples shows user input. Unless other- 
wise indicated, you enter each input line by pressing the 
RETURN key. 


A vertical ellipsis in an example means that information 
not directly related to the example has been omitted. 


mbols and conventions used in syntax formats: 


>~PERCASE WORDS. Uppercase words are DATATRIEVE keywords. Enter 
them exactly as shown. 


vercase words Lowercase words are generic terms that indicate entries 
you must provide. 


Braces mean you must choose one. but no more than 
one, of the enclosed entries. 


wu 
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Brackets mean you have the option of choosing one, but 
no more than one, of the enclosed entries. 


A horizontal ellipsis means you have the option of 
repeating the preceding element of the syntax format. 


A vertical ellipsis in a syntax format means you can 
repeat the syntax element on the preceding line. 


These are called double quotation marks. 


These are called single quotation marks. 


Technical Changes and New Features 


1is section describes the new features for DATATRIEVE documented in this 
anual. 


srsion 3.3 of DATATRIEVE provides limited support for the Rdb segmented 
ring data type. This support lets you store and retrieve Rdb records that contain 
Ids with the segmented string data type. 


»e Section 15.9 for more information on using segmented strings with 
ATATRIEVE. a 


e the Release Notes for a description of all technical changes to 
ATATRIEVE. 
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Part 1 
Understanding DATATRIEVE 


Understanding DATATRIEVE 1 


1is chapter reviews basic DATATRIEVE concepts that were presented in 
hapter 1 of the VAX DATATRIEVE Handbook and explained in greater detail 
later chapters of the Handbook. If you have read the Handbook, you will find 
ost information in this chapter familiar to you. If you have some programming 
ickground, this chapter provides basic information about DATATRIEVE and 
ie range of functions it performs. In addition, there is a section that explains 
ytional software products you can use with DATATRIEVE that might be avail- 
le on your system. 


1. Starting and Ending a DATATRIEVE Session 


2 start a DATATRIEVE session, begin at DCL command level and use the com- 
and RUN SYS$SYSTEM:DTR32xx. The suffix xx is sometimes necessary to 
entify the image of DATATRIEVE you want to run. See the person who | 
stalled DATATRIEVE on your system to determine if you need to specify a suf- 
« and, if you do, what characters you type in place of xx. For example, if you 
ant to run the version of DATATRIEVE that uses TDMS, you may need to 
clude the suffix TD: 


RUN SYS$SYSTEM: DTR32TD 

X Datatrieve V3 

‘C Query and Report System 
‘pe HELP for help 

R> 


ne startup banner shows that you have successfully invoked DATATRIEVE. 
ote that the message you receive in response to your request should specify the 
rsion ee DATATRIEVE you are running. If it does not, consult the person 
‘sponsible for VAX DATATRIEVE at your site. 
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To simplify this command. you can assign a symbol to it in your LOGIN.COM 
file. To use DTR32 to invoke the version of DATATRIEVE in the previous exam- 
ple, enter: | 


$ DIR32 :== $SYS$SYSTEM: DTR32TD 
$ DTR32 

VAX Datatrieve V3 

DEC Query and Report System 

Type HELP for help 
DTR> 


To end your DATATRIEVE session if you are at a DTR> prompt, type EXIT an 
press the RETURN key or use CTRL/Z. Either returns you to the VMS system 
prompt. If you are ata CON>, DFN>, or RW> prompt, use CTRL/Z to get to 
the DTR> prompt. Then use CTRL/Z again or type EXIT and press the 
RETURN key. 


1.2 Writing a DATATRIEVE Session to a Log File 


You can use the DATATRIEVE OPEN command to create a record of your 
DATATRIEVE session in a file in a VMS directory. At any point in the session 
you can issue the CLOSE command and save all of the session up to that point. I 
you do not end the creation of the log file with a CLOSE command, 
DATATRIEVE automatically closes the file when you EXIT from DATATRIEVE 


In this example the log file name is MONTHLY RPT.LOG, but you can specify 
any file name you want: 


DTR> OPEN MONTHLY_RPT.LOG 

DTR> :MONTHLY_RPT 

DTR> CLOSE ! Do not enter the file name following CLOSE. 
DTR> EXIT 


See the VAX DATATRIEVE Reference Manual for more information about the 
OPEN and CLOSE commands. 
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3 DATATRIEVE Concepts and Terminology 


\e following sections review these concepts and terms: 


Databases 

DATATRIEVE domains 
Common Data Dictionary 
Commands and statements 
Procedures 

Command files 
DATATRIEVE view domains 
Tables 

Distributed data 


3.1 Databases 
ATATRIEVE can access three different types of databases: 


File-structured databases that you set up with DATATRIEVE 

Databases that you create using VAX Rdb 

Databases that you create using VAX DBMS 
samples in this book show you how to create your own file-structured databases. 
1apters 14 and 15 explain how to access data stored in DBMS and Rdb 
itabases. 
3.2 DATATRIEVE Domains 


hen you manage information with DATATRIEVE, you access data through con- 
ructs called domains. A domain definition establishes a name for a set of data 

id tells DATATRIEVE where that data is described and where the data is 

ored. A domain definition contains the name of the domain, the name of a 

cord (data description), and the name of a data file. 


the domain is a DATATRIEVE DBMS domain or DATATRIEVE Rdb domain, 
contains the name of a DBMS or Rdb database. 
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You create the domain definition, and the record definition and file that the 
domain uses. You can do this by invoking ADT (Application Design Tool), or you 
can create all three definitions using different forms of the DEFINE command. 
Chapter 1 of the VAX DATATRIEVE Handbook discusses using ADT to create ; 
database. Chapters 10, 11, and 12 of the handbook discuss defining domains, 
records, and files without ADT. 


If you want to use DATATRIEVE to access a database managed by VAX Rdb or 
VAX DBMS, you do not create record or file definitions because the database is 
not file-structured. The database has already been created using VAX Rdbor _ 
VAX DBMS. However, you may want to create a domain definition to let 
DATATRIEVE know how and where your data is stored. Chapter 14 and Chapter 
15 describe DBMS and Rdb domains in greater detail. 


After you have created a DATATRIEVE domain, you refer to its data by using 
the domain name in your DATATRIEVE commands and statements. 


1.3.3 Common Data Dictionary 


DATATRIEVE uses the VAX Common Data Dictionary (CDD) to store data defi- 
nitions and procedures. The CDD is a VAX software product that you always hav: 
on your system if you are using DATATRIEVE. 


In an information management system, reliable data definitions are as important 
as the data itself. The manager of the system or the person in charge of data 
administration must know how data is represented and how it is used by different 
applications running on the system. Shared data definitions must be 
unambiguous, and sensitive data definitions must be protected. The CDD assists 
in these tasks by providing a central storage place for data definitions and a data 
security system for their protection. 


The CDD is actually a hierarchy of dictionaries. A dictionary is to the CDD what 
a directory is to the VMS operating system. Just as you enter a default directory 
when you log in to your VMS system, you enter a default dictionary when you 
start DATATRIEVE. As you can create new VMS directories and move from one 
to another, you can create new dictionaries and move among them using 
DATATRIEVE commands. 


Remember, however, that dictionaries do not contain data files. They store only 
definitions and the security information connected with those definitions. Data 
files always reside in VMS directories. 
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3.4 Commands and Statements 


ju use Commands and statements to manage information with DATATRIEVE. 
ost of the commands deal with the CDD and perform the data description func- 
ms of DATATRIEVE. The following two commands, for instance, tell 
ATATRIEVE you want CDD$TOP.DTR$USERS.WARTON to be your current 
‘tionary, and you plan to store records in a domain named PERSONNEL: 


R> SET DICTIONARY CDD$TOP . DTR$USERS . WARTON 
R> READY PERSONNEL WRITE = 
R> . 


‘her examples of commands are DEFINE DOMAIN, REDEFINE DOMAIN, 
JIT, DELETE, FINISH, and RELEASE. 


atements, on the other hand, perform the query, report, and data manipulation 
actions of DATATRIEVE. The two statements after the READY command in 
e following example store a record in PERSONNEL and then display that 

cord. In the store operation, DATATRIEVE prompts you to enter each field in 
e record: 


R> READY PERSONNEL WRITE 

R> STORE PERSONNEL 

ter ID: 99039 

ter EMPLOYEE_STATUS: TRAINEE 
ter FIRST_NAME: MAYBEL 

ter LAST_NAME: STREP 

ter DEPT: 132 

ter START_DATE: <TAB><RET> 
ter SALARY: 20456 

ter SUP_ID: 23456 


R> PRINT PERSONNEL WITH ID = "99039" 


FIRST LAST START SUP 
» STATUS NAME NAME DEPT DATE SALARY ID 
339 TRAINEE MAYBEL STREP T32 $20,456 23456 


R> 


her DATATRIEVE statements include FIND. MODIFY, DISPLAY, SELECT, 
d so on. 


iu can combine statements into compound statements (BEGIN-END, THEN), 
mplex logical structures with loops (FOR, REPEAT, WHILE), and conditional 
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transfers (IF-THEN-ELSE, ABORT). The following statements retrieve and ther 
display records of all the employees in department T32: 


DTR> FOR PERSONNEL WITH DEPT EQUAL "T32" PRINT 


FIRST LAST ~ START SUP 

ID STATUS NAME NAME DEPT DATE SALARY ID 
38462 EXPERIENCED BILL SWAY T32 5-May-1980 $54,000 00012 
48573 TRAINEE SY KELLER T32 2-Aug-1981 $31,546 87289 
83764 EXPERIENCED LES WHART T32 4-Apr-1980 $41,029 87289 


DTR> 


See the VAX DATATRIEVE Reference Manual for a description of all the 
DATATRIEVE commands and statements. 


1.3.5 Procedures 


Many applications of VAX DATATRIEVE involve sequences of commands and 
statements that recur frequently. You can avoid retyping such a sequence by sto! 
ing it in the CDD as a procedure. With the DEFINE PROCEDURE command, 
you give the recurring sequence a name and enter both the name and the 
sequence into the CDD. You invoke the procedure by typing either a colon (:) or 
EXECUTE, followed by the procedure name. DATATRIEVE then executes the 
statements and commands in the procedure. Refer to Chapter 7 for a discussion 
of DATATRIEVE procedures. 


1.3.6 DATATRIEVE Command Files 


You can use DATATRIEVE command files in much the same way you use 
DATATRIEVE procedures. Procedures are stored in the Common Data 
Dictionary, and command files are stored in a VMS directory. Both contain only 
DATATRIEVE commands and statements. You invoke command files at the 
DTR> prompt by typing the at sign (@), followed by the command file 
specification. — 


1.3.7 DATATRIEVE View Domains 


You might want to access data repeatedly that is in more than one domain or. 
restrict someone’s access to a subset of the information that is in a domain. You 
can create a special type of DATATRIEVE domain, a view domain, to help accon 
plish these functions. The definition of a view domain is stored in the CDD, and 
you Can use a view domain in much the same way as you would a “simple” 
domain. Chapter 5 tells you how to create and use view domains. 
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3.8 DATATRIEVE Tables 


10ther type of definition you can create with DATATRIEVE and store in the 
ID is a table definition. DATATRIEVE tables let you: 


Specify one value and retrieve another associated with it 


Validate data according to the presence or absence of a data item in the table 


ATATRIEVE lets you define and use two types of tables: dictionary tables and 
main tables. See Chapter 12 of the VAX DATATRIEVE Handbook and the 
apter on designing better records in this manual for more information on 
fining and using tables. 


3.9 DATATRIEVE Collections 


ATATRIEVE collections are temporary groups of records that you pull together 
mm a larger set of data. The following example creates a collection named 

}PTT32 that contains all employee records from Department T32 and then iso- — 
ies the records of those employees earning more than $30,000: 


R> FIND DEPTT32 IN PERSONNEL WITH DEPT EQ "T32" 
records found] 

R> FIND WELLPAID IN DEPTT32 WITH SALARY GT 30000 
records found 

R> PRINT: 

record selected, printing whole collection. 


FIRST LAST START SUP 
0 STATUS NAME NAME DEPT DATE SALARY ID 
462 EXPERIENCED BILL SWAY T32 5-May-1980 $54,000 00012 
573 TRAINEE SY KELLER T32 2-Aug-1981 $31,546 87289 
764 EXPERIENCED JIM MEADER T32  4-Apr-1980 $41,029 87289 


ie collections DEPTT32 and WELLPAID are available for use until you decide 
remove them or until you exit from DATATRIEVE. Collections are useful 

len you are learning DATATRIEVE or first thinking about an application. 

‘ing FIND statements parallels the way most of us think when retrieving data; 
at is, we use a Series of steps to narrow down a group of records to just the ones 
‘want. 


3.10 Distributed Data 


ith VAX DATATRIEVE, you can easily access domains defined on other sys- 
ns that. are linked to yours by DECnet. The other system must have VAX 
ATATRIEVE, DATATRIEVE-11, or DATATRIEVE-20 installed. 
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1.4 What DATATRIEVE Can Do for the Programmer 


You do not have to have a programming background to use DATATRIEVE. 
However, if you do have programming experience, you probably want to know 
how DATATRIEVE is different from the languages you have used before. 


DATATRIEVE is a fourth-generation language. Its syntax is more ”English-like’ 
than that of COBOL or BASIC, and it has a strong nonprocedural aspect. It 
executes commands as you type them, and you can often simply tell 
DATATRIEVE what information you want by name, instead of specifying how to 
obtain that information. 


DATATRIEVE provides the same data storage capabilities that you have with 
other languages. It can store and retrieve data using existing RMS data files of 
any type. It can also create sequential and multikey indexed files. However, you 
cannot create a relative file with DATATRIEVE. 


DATATRIEVE allows you to set up data hierarchies (as in a COBOL group item) 
and repeating fields (as ina COBOL OCCURS clause). Retrieving data from 
repeating fields (called /istsin DATATRIEVE terminology) is not as easy as 
retrieving data from other types of fields. Be sure to take this fact into consider- 
ation before you decide to use DATATRIEVE’s OCCURS clause. 


In COBOL or BASIC, each program describes the structure of input and output 

records. DATATRIEVE lets you define records and store record definitions sepa- 
rately from a program. Then you can write any number of programs that use the 
records you have defined, without redefining the record each time. 


DATATRIEVE also handles other common language functions automatically, 
without the need for language statements. For instance, DATATRIEVE: 

e Finds data files, opens them, ‘and performs input/output operations 

e Labels columns in an output display 

e Converts data types 

e Formats data for output 


¢ Handles conditions like end-of-file and matching 
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s a result, you can save many lines of code, get applications running quickly, and 
ave code that is more readable than languages such as COBOL or BASIC. 


sing the DATATRIEVE Call Interface, you can also include DATATRIEVE 
nctions in a program written in another language. The Call Interface is used 
ost often in two ways: 


You can use the linkage section of your program to do file access entirely 
through DATATRIEVE. In this way, the calling program does not need to 
specify the structure of the data, and you do not need to relink programs 
when the data files change. 


You can write a program that passes commands and statements to 
DATATRIEVE. The program can present the user with a customized inter- 
face, such as a menu. In this way, you can “hide” DATATRIEVE from users 
who do not know how to use its commands and statements. | 


1e VAX DATATRIEVE Guide to Customizing and Programming explains how 
mu can use DATATRIEVE with other languages. 


5 The Sample Domains, Records, and Data Files 


1e VAX DATATRIEVE installation kit includes several sample domains: 
AMILIES, PERSONNEL, and YACHTS, among others. The domain definitions 
id the record definitions (FAMILY REC, PERSONNEL REC, and YACHT, for 
‘ample) are stored in the Common Data Dictionary in the directory called 
DD$TOP.DTR$LIB.DEMO. 


1e data files, such as FAMILY.DAT, PERSON.DAT, and YACHT.DAT, are 
ored in the library directory DTR$LIBRARY. 


you want to use these domains to follow the examples in the VAX 
ATATRIEVE documentation and to practice using DATATRIEVE commands 
id statements, you should copy the data files to your default VMS directory. 
yu can use the VMS COPY command to transfer the data files to your default 
MS directory. For example, to copy FAMILY.DAT, enter: 


COPY DTR$LIBRARY:FAMILY.DAT  * 


) get access to the domain and record definitions stored in the Common Data 
ctionary, you can set your default dictionary directory to the DEMO directory. 
ter you invoke VAX DATATRIEVE, enter this command: 


- SET DICTIONARY CDD$TOP .DTR$LIB.DEMO 
> 
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To see that the sample domain and record definitions are in place, use the SHOV 
command: 


DTR> SHOW DOMAINS, RECORDS 


Domains: 
ANNUAL_REPORT ; 1 FAMILIES ;1 KETCHES ; 2 OWNERS ; 1 
OWNERS_SEQUENTIAL; 1 PAYABLES ; i PERSONNEL; 1 
PETS;1 PROJECTS ;1 SAILBOATS; 1 SALES ;1 
YACHTS; 1 YACHTS_SEQUENTIAL;1 

Records: , 
ANNUAL_REC; 1 DAB; 1 FAMILY_REC;1 OWNER_RECORD; 1 
PAYABLES_REC ; 1 PERSONNEL_REC;1 PET_REC;1i PROJECT_REC;1 
SALES_REC;1 YACHT; 1 

DTR> 


The results of this command vary from one system to another. but you should be 
sure that the domain and record definitions you need are listed among those that 
DATATRIEVE displays on your terminal. 


If you cannot copy the data files from DTR$LIBRARY, cannot get access to the 
DEMO directory, or cannot find the domain and record definitions in the DEMO 
directory, see the person responsible for VAX DATATRIEVE on your system. 


1.6 Using SET Commands to Control Output 


When you invoke VAX DATATRIEVE, it sets several characteristics that contrc 
your display of input and output. You can display these settings with the SHOW 
SET_UP command: 


DTR> SHOW SET_UP 
Set-up: 
Columns-page: 80 
No abort 
Prompt 
No search 
Form 
No verify 
No semicolon 
No lock wait 
DTR> 


The settings shown in the example are the default settings. You can change thes 
characteristics at any time during a DATATRIEVE session by using the forms c 
the SET command discussed in the following pages. 


1.6.1. Changing the Columns-Page Setting 


The default for the columns-page setting is 80 characters, the width of most vide 
display screens. You can change this setting to fit your application and terminal 
characteristics: 
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6.1.1 Increasing the Columns-Page Setting -- You may want to increase the 
)lumns-page setting if you have a VT100-family or hardcopy terminal. Before 

yu can display lines more than 80 characters long, you must set your terminal to 
low the display of long lines. This is a two-step process: 


Use the DCL SET TERMINAL command to tell your system to increase 
the width of lines it can send you: 


: SET TERMINAL/WIDTH=132 


Alternatively, within DATATRIEVE you can use the function: 


DTR> FN$WIDTH(132) 
DTR> 


'. Use the SET COLUMNS PAGE command to increase the length of the 
line DATATRIEVE can display on your terminal. The maximum limit on 
the columns-page setting is 255. 


DTR> SET COLUMNS_PAGE = 132 
DTR> 


hatever the column setting on your terminal, you can continue a long input line 
r using a hyphen (-) at the end of the line. When you use a hyphen, 
ATATRIEVE does not check the syntax of your input until you press RETURN 
ter a line that does not end in a hyphen. If the line you want to extend ends 

th a complete word, separate the hyphen from the word by entering a space. 
therwise, DATATRIEVE considers the characters at the beginning of the next 
1e to be part of the same character string. 


du cannot enter more than 255 characters on an extended input line. 


6.1.2 Decreasing the Columns-Page Setting -- To decrease the number of 
lumns displayed. simply enter a SET COLUMNS PAGE command: 


R> SET COLUMNS_PAGE = 60 
R> 
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1.6.2 Using SET ABORT 


When DATATRIEVE executes an ABORT statement in a command file or proce 
dure while SET NO ABORT is in effect, it affects only the compound statement 
containing the ABORT statement. If SET ABORT is in effect, DATATRIEVE 
terminates the remainder of the command file or procedure. The same rules app] 
if you enter a CTRL/Z in response to a prompt. 


If DATATRIEVE encounters a syntax or logical error in a command file or proce 
dure, it returns you to the DTR> prompt whether or not you have used SET 
ABORT. 


SET NO ABORT is the default setting when you invoke DATATRIEVE. 


See Chapters 7 and 8 for a discussion of using ABORT and NO ABORT in con- 
trolling procedures and command files. 


1.6.3. Using SET PROMPT 


When you invoke DATATRIEVE, SET PROMPT is in effect. If you press 
RETURN before finishing a command or statement, DATATRIEVE prompts yo 
for the remaining required elements of that command or statement. 


The following sequence of commands and statements shows how DATATRIEVE 
responds when SET PROMPT is in effect. After the line of text indicates the 
next required element, DATATRIEVE displays the CON > (continuation) promr 
As long as the syntax of a command or statement is incomplete, DATATRIEVE 
uses CON > to tell you it is ready for further input. 


DTR> READY : 
[Looking for dictionary path name] 


CON> YACHTS 

DTR> FIND 

(Looking for "FIRST", domain name, or collection name] 
CON> FIRST . 

[Looking for value expression] 

CON> j 

[Looking for name of domain, collection, or list] 


CON> YACHTS 
[1 record found] 
DTR> 


Notice that DATATRIEVE stops prompting as soon as you enter elements that 
comprise a syntactically complete command or statement. For example, READ‘ 
YACHTS is complete, and DATATRIEVE does not prompt for any further ele- 
ment. Similarly, when you enter FIND FIRST 1 YACHTS, DATATRIEVE does 
not prompt you for a CROSS clause, a Boolean expression, or a SORTED BY 
clause. 
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hen SET NO PROMPT is in effect, DATATRIEVE does not display the text 
out the next required element. It does, however, use the CON > prompt when 
e syntax is incomplete. This identical sequence of inputs shows how 
ATATRIEVE responds when SET NO PROMPT is in effect: 


R> SET NO PROMPT 
R> FIND 

N> FIRST 

N> 4 

N> YACHTS 
spucere found] 

> 


ite that SET NO PROMPT does not suppress the messages DATATRIEVE 
splays about the results of commands and statements. 


3.4 Using SET SEARCH 


mu activate the DATATRIEVE Context Searcher with the SET SEARCH com- 
and. The Context Searcher is a facility to help you get easy access to list items 
d DBMS sets. It automatically searches lists and DBMS sets when necessary 
resolve the names of data items. NO SEARCH is the default setting. See 
.apter 6 for a discussion of the Context Searcher. 


3.5 Using SET FORM 


1T FORM is the default when you start a DATATRIEVE session. You can con- 

| whether or not DATATRIEVE uses forms to display records on your VT52-, 

*100- or VT200-family terminal. SET FORM must be in effect both when you 

t access to a domain whose definition includes a FORM clause and when you 

ter PRINT, STORE, or MODIFY commands related to that domain. SET NO 

)RM prevents DATATRIEVE from using its forms interface. See Chapter 13 
a discussion of using forms with DATATRIEVE. 


3.6 Using SET VERIFY 


\TATRIEVE’s SET VERIFY command displays lines from DATATRIEVE 
nmand files when those command files are invoked. It also displays the con- 
its of the edit buffer when you exit an edit buffer from within DATATRIEVE. 


'T VERIFY does not display lines from command files run from the DCL 

ympt in an invocation command line, unless the command file itself contains a 
‘T VERIFY command. And SET VERIFY does not display lines from 
\TATRIEVE procedures stored in the CDD, whether they are run from within 
\TATRIEVE or from the DCL prompt. (See the section later in this chapter for 
re information on issuing DATATRIEVE commands from the DCL prompt.) 
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SET NO VERIFY turns off display of command file lines. The SHOW SET UP 
command tells you whether SET VERIFY or SET NO VERIFY is in effect durin 
your DATATRIEVE session. 


There are comparable DCL settings, SET VERIFY and SET NOVERIFY. If DC 
SET VERIFY is in effect, lines from DATATRIEVE command files run from the 
DCL prompt are displayed. 


You may want to use SET VERIFY as a debugging tool for DATATRIEVE proce 
dures. You can do this by either: 


e Creating your DATATRIEVE procedures in a command file at VMS level 
and executing them at the DTR> prompt 


¢ Writing your DATATRIEVE procedures to a command file from an edit 
buffer or with the EXTRACT command, deleting the DEFINE 
PROCEDURE or REDEFINE PROCEDURE syntax, and executing that 
command file from DATATRIEVE 


If there is a syntax.error, you can see exactly where it occurs in the procedure. 
After you have debugged a procedure, you can then store it in the CDD. 


1.6.7 Using SET SEMICOLON 


When you change the setting to SET SEMICOLON, DATATRIEVE requires 
that you put a semicolon at the end of every statement you enter. DATATRIEV] 
returns a CON > prompt each time you press RETURN to tell you the statemen 
is still incomplete. SET NO SEMICOLON is the default at the start of your 
DATATRIEVE session. 


If you are entering a compound statement incorporating more than one logically 
complete statement. SET SEMICOLON enables you to end a component state- 
ment at the end of a line without having DATATRIEVE execute the statement 

immediately. When you have entered all the parts of the statement, you enter a 
semicolon and DATATRIEVE executes the entire statement. 


1.6.8 Using SET LOCK WAIT 


SET NO LOCK WAIT is the default setting. With this setting. DATATRIEVE 
tries to access a locked record for 12 seconds. If the record does not become 
accessible during that period, you receive an error message and DATATRIEVE 
continues. If you have LOCK WAIT set, DATATRIEVE keeps accessing a locke 
record indefinitely until it becomes available. For a discussion of locked records, 
see the material on the READY command in the VAX DATATRIEVE Referenc 
Manual. 
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.7 Controlling the Input of Dates and Currency 


‘ou can define VMS logical names to control the way DATATRIEVE handles the 
iterpretation of dates and currency symbols. You can control the format 
JATATRIEVE uses to interpret the input of dates by defining the Logical Name 
ITRSDATE INPUT. This logical name affects only the interpretation of the 

iput of dates and has nothing to do with the edit strings used for the output of 
ates. 


‘ou define DTR$DATE INPUT with a three-character string containing one D 
or day, one M for month, and one Y for year. Enclose the three-character string 
1 quotation marks. 


he command DEFINE DTR$DATE INPUT “MDY” defines a date input of 
3/12/09 as March 12, 1909. (MDY is the default interpretation DATATRIEVE 
ses for input of dates if you do not define DT[R$DATE INPUT.) 


able 1-1 shows the different combinations you can use. 


able 1-1: Defining the Logical Name DTRSDATE INPUT 


ee 






Format 




















“MDY” 03/12/09 March 12 1909 
“DMY” 03/12/09 December 3 1909 
“YDM” 03/12/09 September 12 1903 
“YMD” 03/12/09 December 9 1903 
“DYM” 03/12/09 September 3 1912 








“MYD” 03/12/09 





March 9 1912 


he format you choose also controls the format DATATRIEVE uses to convert 
x-digit numeric strings (such as 810210) to dates. 


ou can define DTR$DATE INPUT at DCL command level (indicated by the dol- 
r sign prompt), or you can put the appropriate DEFINE command in your login 
ymmand file. 
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Table 1-2 shows the three logical names you can define to control the currency 
defaults of the VMS operating system. © 


Table 1-2: Currency Symbols 


Logical Name 


SYS$CURRENCY 






“s . Default 







SYS$DIGIT_SEP 
SYS$RADIX_ POINT 


The following examples demonstrate the effects of redefining these logical names 
In the first example, you redefine the default values: 


$ DEFINE SYS$CURRENCY "#" 
$ DEFINE SYS$DIGIT_SEP "." 
$ DEFINE SYS$RADIX_POINT "," 


In the next example, you can see the results of the changed definitions: 


DTR> DECLARE NUM PIC 9(6)V99. 
DTR> NUM = 12345.67 
DTR> PRINT NUM USING $$$, $$$.99 


NUM 
#12 .345 ,67 


DTR> 


1.8 Issuing DATATRIEVE Commands from DCL Command 
Level 


When you define a DCL symbol for invoking VAX DATATRIEVE, make sure yot 
use the dollar sign ($) instead of the DCL RUN command. For example, define 
the name as the equivalent of SS YS$SYSTEM:DTR32, not RUN 
SYSSSYSTEM:DTR32. Defining the symbol this way lets you include 
DATATRIEVE commands and statements on the same line you use to start VAX 
DATATRIEVE. For example: 


$ DTR32 :== $SYS$SYSTEM:DTR32 
$ DTR32 READY YACHTS; PRINT FIRST 3 YACHTS 


DCL command lines that contain DATATRIEVE commands and statements are 
also called invocation command lines. On a command line like this, you can put 
any legal combination of DATATRIEVE commands and statements, including thi 
invocations of DATATRIEVE procedures and command files. Separate each com: 
mand or statement with a semicolon. 
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ATATRIEVE executes the commands and statements in the sequence you enter 
em. When DATATRIEVE finishes executing those commands and statements, 
automatically ends your session and returns to the DCL prompt. 


1is example shows how the invocation command line operates: 


DTR32 READY YACHTS; PRINT FIRST 3 YACHTS 


LENGTH | 
OVER 

NUFACTURER MODEL RIG ALL WEIGHT BEAM PRICE 

LBERG 37 MK II KETCH 37 20,000 12 $36,951 

LBIN 79 SLOOP 26 4,200 10 $17,900 

LBIN BALLAD SLOOP 30 7,276 10 $27,500 


your invocation command line contains any of the following elements, 
ATATRIEVE prompts you for input before returning you to DCL command 
vel: . . 


STORE and MODIFY statements without USING clauses 

Prompting value expressions | 

ADT 

SET GUIDE 

EDIT 
the DCL command line that invokes DATATRIEVE is embedded in a DCL 
ymmand procedure and DATATRIEVE prompts for input, you must reassign 


ie logical name SYS$INPUT. See the section on using DCL command files in 
hapter 8 for more information. 


.9 Using a DATATRIEVE Startup Command File 


you frequently start your DATATRIEVE sessions with the same series of com- 
ands and statements, you can put them in a DATATRIEVE command file: 


With a text editor, create a file containing the DATATRIEVE commands 
and statements just as you would enter them in an interactive session but 
without any of the DATATRIEVE prompts (DTR>, CON>, DFN>. 

RW >). 
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Here is a sample command file: 


DECLARE X USAGE DATE. 

X = "NOW" 

IF FN$HOUR(X) BT 6 11 THEN PRINT SKIP, “GOOD MORNING." ELSE 

IF FN$HOUR(X) BT 12 16 PRINT SKIP, "GOOD AFTERNOON." ELSE 

PRINT SKIP, “YOU STILL HERE?" 

READY CDD$TOP.DTR$LIB.DEMO. YACHTS, 
CDD$TOP .DTR$LIB.DEMO.OWNERS, 
CDD$TOP . DTR$LIB.DEMO.FAMILIES 

SHOW READY 

SHOW DICTIONARY 


2. In your LOGIN.COM file or at DCL level. use the DCL DEFINE command 
to define DTRSSTARTUPFP as a logical name for your startup command file: 


$ DEFINE DTR$STARTUP "device: [username] DTRSTART.COM" 


When you invoke DATATRIEVE, it translates the logical name 
DTRSSTARTUP and executes the command file, including any output it 
generates, before it displays the first DTR> prompt on your terminal. 


You can include in your DTR$STARTUFP file any of the SET commands to estab- 
lish the default settings for your DATATRIEVE session. You can also establish 
synonyms for any DATATRIEVE keywords, using the DECLARE SYNONYM 
command. See the description of DECLARE SYNONYM in the VAX 
DATATRIEVE Reference Manual. 
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Part 2 
Manipulating Data 


Writing Record Selection Expressions 2 


1ce you have defined and stored your data. you probably want to manipulate it 
some way. Typical operations that you perform when you access data are: 


Displaying a group of records (PRINT, LIST, REPORT, or PLOT 
statements) 

Forming a temporary collection of records (FIND statement) 
Updating or changing a group of records (MODIFY statement) 


2>fore performing any of these operations, you must first decide which records 
12 want to work with. You select those target records using a record selection 
pression (RSE). The RSE identifies which records you want to work with and 
rms a record stream, that is, a group of records from a domain or collection. 
ATATRIEVE performs the specified operation on every record in the record 
ream. 


re selected records can come from any of the following sources: 


Domains 
Collections 
Lists 

Rdb relations 
DBMS records 


The RSE determines the content of the record stream. By including various 
clauses in the RSE, you can: 


e Specify the number of records in the record stream (FIRST n, ALL clauses) 


e Limit the record stream to records that meet a conditional test (WITH 
clause) 


e Reduce the records in a record stream to unique values (REDUCED TO 
clause) 


e Sort the records according to the values of one or more fields (SORTED BY 
clause) 


e Join records from one or more domains or collections (CROSS clause) 


e Access member or owner records of a DBMS set, (MEMBER, OWNER, or 
WITHIN clauses) 


You may want to select records using a combination of these ways. An RSE can 
include any or all of the clauses listed. The following FIND statement includes a 
record selection expression that combines records from different sources, limits 
the records in the record stream to those that meet a particular condition, and 
sorts the records according to the value of two fields: 


FIND EMPLOYEES CROSS 
JOB_HISTORY OVER 
EMPLOYEE_ID WITH 

JOB_END MISSING SORTED BY 
DEPARTMENT_CODE, LAST_NAME 


When you are writing complex RSEs like this one, it is useful to indent parts of 
the expression so that you can easily see which relations are being crossed, whict 
field values are used for selecting the records, and which fields are used for the 
sorting. The indentation helps you to see different parts of the RSE: it does not 
affect how the statement executes. 


This chapter presents many examples to teach you how to use RSEs, an impor- 
tant tool of the DATATRIEVE language. It begins with simple RSEs and shows 
you how to use each clause of the RSE so that you can build complex RSEs. The 
examples show RSEs in PRINT statements, but you can also use them in all of 
the following DATATRIEVE statements: 


e ERASE 
e FIND 

e FOR 

e LIST 


2-2 Writing Record Selection Expressions 


MATCH 
MODIFY 
PLOT 
REPORT 


Restructure 


addition, you can use RSEs to specify subsets of records when you define view 
mains. See Chapter 5 for examples of RSEs in view domain definitions. 


is chapter illustrates all of the previously listed operations except for accessing 
»ords in a DBMS set, which is discussed in Chapter 14. In addition, a form of 

2 RSE allows you to access list items from hierarchical records. This is dis- 
ssed in Chapter 6. 


1 Displaying All the Records in a Domain 


a domain does not contain many records, you may want to display all of the 
‘ords. In that case, you use the simplest form of an RSE, the domain name by 
elf. Because you want DATATRIEVE to print all of the records in that domain, 
u do not use any clauses of the RSE to select specific records. For example: 


’> READY PERSONNEL 
2> PRINT PERSONNEL 


FIRST LAST START SUP 
) STATUS NAME NAME DEPT DATE SALARY ID 
)12 EXPERIENCED CHARLOTTE SPIVA TOP 12-Sep-1972 $75,892 00012 
391 EXPERIENCED FRED HOWL Fil 99-Apr-1976 $59,594 00012 
343 EXPERIENCED CASS TERRY D98 2-Jan-1980 $29,908 39485 
343 TRAINEE: JEFF TASHKENT C82 4-Apr-1981 $32,918 87465 
132 TRAINEE THOMAS SCHWEIK Fil 77-Nov-1981 $26,723 00891 
156 TRAINEE HANK MORRISON T32 14-Mar-1982 $30,000 87289 
162 EXPERIENCED BILL SWAY T32 5-May-1980 $54,000 00012 
165 EXPERIENCED JOANNE FREIBURG E46 20-Feb-1980 $23,908 48475 
185 EXPERIENCED DEE TERRICK D98 2-May-1977 $55,829 00012 
175 EXPERIENCED GAIL CASSIDY E46 2-May-1978 $55,407 00012 
»73 TRAINEE SY KELLER T32 2-Aug-1981 $31,546 87289 
)01 EXPERIENCED DAN ROBERTS C82 77-Jul-1979 $41,395 87465 
343 TRAINEE BART HAMMER D98 4-Aug-1981 $26,392 39485 
923 EXPERIENCED LYDIA HARRISON F1i 19-Jun-1979 $40,747 00891 
'64 EXPERIENCED JIM MEADER T32 4-Apr-1980 $41,029 87289 
375 EXPERIENCED MARY NALEVO D98 3-Jan-1976 $56,847 39485 
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87289 EXPERIENCED LOUISE DEPALMA G20 28-Feb-1979 $57,598 00012 
87465 EXPERIENCED ANTHONY IACOBONE C82 2-Jan-1973 $58,462 00012 


87701 TRAINEE NATHANIEL CHONTZ Fil 28-Jan-1982 $24,502 00891 
88001 EXPERIENCED DAVID LITELLA G20 11-Nov-1980 $34,933 87289 
90342 EXPERIENCED BRUNO DONCHIKOV C82 9-Aug-1978 $35,952 87465 
91023 TRAINEE STAN WITTGEN G20 23-Dec-1981 $25,023 87289 
99029 EXPERIENCED RANDY PODERESIAN C82 24-May-1979 $33,738 87465 
DTR> 


After you ready the domain, the PRINT PERSONNEL statement displays all th 
records in the PERSONNEL domain. The source for the RSE is PERSONNEL, 
the name of the domain. | 


To indicate clearly that you want the record stream to include all the records, yor 
can include the keyword ALL before the source of the RSE. Because the ALL is 
optional, PRINT ALL PERSONNEL is equivalent to PRINT PERSONNEL. 


2.2 Limiting the Number of Records in the Record Stream 


There are several ways to limit the number of records in the record stream. One 
way is to restrict the record stream to the first n records in the domain or collec- 
tion. This type of RSE is useful when you know the order of records and the exa: 
number of records you wish to access. 


To specify the number of records in the record stream, type FIRST followed by < 
number before typing the source for the RSE. For example: 


DTR> PRINT FIRST 5 PERSONNEL 


FIRST LAST START SUP 

ID STATUS NAME NAME DEPT DATE SALARY ID 
00012 EXPERIENCED CHARLOTTE SPIVA TOP 12-Sep-1972 $75,892 00012 
00891 EXPERIENCED FRED HOWL Fii 9-Apr-1976 $59,594 00012 
02943 EXPERIENCED CASS TERRY D98 2-Jan-1980 $29,908 39485 
12643 TRAINEE JEFF TASHKENT C82 4-Apr-1981 $32,918 87465 
32432 TRAINEE THOMAS SCHWEIK Fil 7-Nov-1981 $26,723 00891 


DTR> 


In this case. the RSE is FIRST 5 PERSONNEL. DATATRIEVE displays the 
first five records in PERSONNEL, according to their order in the data file. An 
RSE can have the form FIRST n domain-name or FIRST n collection-name. If n 
is larger than the number of records in the domain or collection, DATATRIEVE 
displays all the records in that source. 
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3 Identifying the Records That Meet a Test 


ten you are interested in grouping similar records together, regardless of their 
ysical position in the data file. You can restrict the record stream to those 
cords that satisfy a specific condition by using the WITH clause of the RSE. 
fferent types of WITH clauses reflect different types of relationships between 
2 values of the same field for different records. Records can be grouped if they 
> related by the following conditions: 


There is a pattern to the characters comprising the field values 
The field values fall into a specified range 
The value for a field is or is not missing 


A field value can or cannot be found in a table 


3.1. Comparing Records by Pattern Recognition 


tu can group records if the characters of a field value match or do not match a 
acified value. For example: 


t> PRINT YACHTS WITH RIG = "MS" 


LENGTH 
OVER 
JUFACTURER MODEL RIG ALL WEIGHT BEAM PRICE 
{ERICAN 26-MS MS 26 5,500 O08 $18,895 
\STWARD HO MS 24 7,000 O09 $15,900 
JORD MS 33 MS 33 14,000 11 
(NDSEY 39 MS 39 14,500 12 $35,900 
}GGER FD M/S MS 35 17,600 11 


i> 


is statement causes DATATRIEVE to examine each record of the YACHTS 
main, displaying only those records with the value MS for the RIG field. 
\TATRIEVE tests each record of YACHTS, identifying and then displaying 
*h record that meets the specified condition. The WITH clause lets you limit 
» record stream to the records you wish to access. 


e expression RIG = “MS” is a Boolean expression. A Boolean expression con- 
ls a comparison between value expressions. A Boolean expression is either true 
false, depending on the values of the field and the value expression specified. 

e term that relates the value expressions is called a relational operator. In this 
ample, the relational operator is an equal sign (=). 
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When you use EQUAL (or = or EQ), NOT EQUAL (NE), or CONTAINING 
(CONT), you can list more than one value expression in the same Boolean. The 
following queries specify a group of value expressions for DATATRIEVE to com- 
pare with each field value: 


DTR> PRINT YACHTS WITH BUILDER = "ALBIN", "ALBERG" 


LENGTH 

OVER 
MANUFACTURER MODEL RIG ALL WEIGHT BEAM PRICE 
ALBIN 79 SLOOP 26 4,200 10 $17,900 
ALBIN BALLAD SLOOP 30 7,276 10 $27,500 
ALBIN VEGA SLOOP 27 5,070 08 $18,600 
ALBERG 37 MK II KETCH 37 20,000 12 $36,951 


DTR> PRINT YACHTS WITH RIG NE "SLOOP", "KETCH" 


LENGTH 
OVER 
MANUFACTURER MODEL RIG ALL WEIGHT BEAM PRICE 
AMERICAN 26-MS MS 26 5,500 O08 $18,895 
EASTWARD HO MS 24 7,000 09 $15,900 
F JORD MS 33 MS 33 14,000 11 
LINDSEY 39 MS 39 14,500 12 $35,900 
ROGGER FD M/S MS 35 17,600 11 


DTR> 


Note that the EQUAL (=) and NOT EQUAL operators are case-sensitive: 


DTR> FIND YACHTS WITH BUILDER = "Albin" 
[O records found 


DTR> FIND YACHTS WITH BUILDER NOT_EQUAL "Albin" 
{113 records found] 


Because the names of builders in the YACHTS domain were entered in uppercas 
letters, DATATRIEVE does not find any record for a builder named " Albin.” 


However. the CONT or CONTAINING operator is indifferent to the case of the 
letters and searches only for a particular sequence of letters. This operator also 
finds matches if there is agreement with a substring derived from the field value 
The CONT operator finds the “ALBIN” records if you specify “Albin” or “bin” | 

three-letter substring) or any other string of letters unique to ALBIN: 


DTR> FIND YACHTS WITH BUILDER CONT "Albin" 
[3 records found 


DTR> FIND YACHTS WITH BUILDER CONT "bin" 
[3 records found 
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the next example, DATATRIEVE finds and displays each record that contains 
her the substring “alb” or the substring “pears” in the value for BUILDER: 


R> PRINT YACHTS WITH BUILDER CONT "alb", "pears" 


LENGTH 
OVER 
NUFACTURER MODEL RIG ALL WEIGHT BEAM PRICE 
LBERG 37 MK II KETCH 37 20,000 12 $36,951 
LBIN 79 SLOOP 26 4,200 10 $17,900 
LBIN BALLAD SLOOP 30 7,276 10 $27,500 
LBIN VEGA SLOOP 27 5,070 08 $18,600 
EARSON 10M SLOOP 33 12,441 11 
EARSON 26 SLOOP 26 5,400 08 
EARSON 26W SLOOP 26 5,200 09 
EARSON 28 SLOOP 28 7,850 O09 
EARSON 30 SLOOP 30 8,320 09 
EARSON 35 SLOOP 35 13,000 10 
EARSON 36 SLOOP 37 13,500 11 
EARSON 365 KETCH 36 17,700 11 
EARSON 39 SLOOP 39 17,000 12 
EARSON 419 KETCH 42 21,000 13 


R> 


hen you want to find records with a field value starting with a particular 
bstring, use the STARTING WITH relational operator. For example, you might 
int to display data on all builders beginning with the letter “A” or with the 
bstring ” Al”: | 


R> PRINT YACHTS WITH BUILDER STARTING WITH "A"" 


LENGTH 

OVER 
NUFACTURER MODEL RIG ALL WEIGHT BEAM PRICE 
LBERG 37 MK II KETCH 37 20,000 12 $36,951 
LBIN 79 SLOOP 26 4,200 10 $17,900 
LBIN BALLAD SLOOP 30 7,276 10 $27,500 
LBIN VEGA SLOOP 27 5,070 08 $18,600 
MERICAN 26 SLOOP 26 4,000 O08 $9,895 
MERICAN 26-MS MS 26 5,500 O08 $18,895 
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DTR> PRINT YACHTS WITH BUILDER STARTING WITH "AL" 


LENGTH 

OVER 
MANUFACTURER MODEL RIG ALL WEIGHT BEAM PRICE 
ALBERG 37 MK II KETCH 37 20,000 12 $36,951 
ALBIN 79 SLOOP 26 4,200 10 $17,900 
ALBIN BALLAD SLOOP 30 7,276 10 $27,500 
ALBIN VEGA SLOOP 27 5,070 08 $18,600 


DTR> 


Note that the STARTING WITH relational operator is case-sensitive. If you do 
not specify the correct case of each character in the substring, DATATRIEVE 
does not find the record: 


DTR> FIND YACHTS WITH BUILDER STARTING WITH "al" 
[O records found 
DTR> 


2.3.2 Grouping Records When Values Fall Within a Range 


DATATRIEVE lets you use a variety of relational operators to test if a field valu 
for a record falls within a specified range. These operators are: 


¢ GREATER THAN (>, GT. or AFTER) 
¢ GREATER EQUAL (GE) 

¢ LESS THAN (<, LT, or BEFORE) 

¢ LESS EQUAL (LE) 

¢ BETWEEN (BT) 


For example: 


DTR> PRINT PERSONNEL WITH SALARY GREATER_THAN 54000 


FIRST LAST START SUP 

ID STATUS NAME NAME DEPT DATE SALARY ID 
00012 EXPERIENCED CHARLOTTE SPIVA TOP 12-Sep-1972 $75,892 00012 
00891 EXPERIENCED FRED HOWL Fil 99-Apr-1976 $59,594 00012 
39485 EXPERIENCED DEE TERRICK D98 2-May-1977 $55,829 00012 
48475 EXPERIENCED GAIL CASSIDY E46 2-May-1978 $55,407 00012 
84375 EXPERIENCED MARY NALEVO D98 3-Jan-1976 $56,847 39485 
87289 EXPERIENCED LOUISE DEPALMA G20 28-Feb-1979 $57,598 00012 


87465 EXPERIENCED ANTHONY IACOBONE C82 2-Jan-1973 $58,462 00012 
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R> PRINT PERSONNEL WITH SALARY GREATER_EQUAL 54000 


FIRST LAST START SUP 
D STATUS NAME NAME DEPT DATE. SALARY ID 
012 EXPERIENCED CHARLOTTE SPIVA TOP 12-Sep-1972 $75,892 00012 
891 EXPERIENCED FRED HOWL Fil 9-Apr-1976 $59,594 00012 
462 EXPERIENCED BILL SWAY T32 5-May-1980 $54,000 00012 
485 EXPERIENCED DEE TERRICK D98 2-May-1977 $55,829 00012 
475 EXPERIENCED GAIL CASSIDY E46 2-May-1978 $55,407 00012 
375 EXPERIENCED MARY NALEVO D98 3-Jan-1976 $56,847 39485 
289 EXPERIENCED LOUISE DEPALMA G20 28-Feb-1979 $57,598 00012 


465 EXPERIENCED ANTHONY IACOBONE C82 2-Jan-1973 $58,462 00012 


yte the difference between the two record streams. Bill Sway, who earns exactly 
4.000. is included in the record stream when the Boolean expression is 
iALARY GREATER EQUAL 54000.” But he is excluded when the 

tEATER THAN operator is used. In other words, GREATER EQUAL. 

‘ludes a record if a field value is equal to the value expression specified, but 
tEATER. THAN leaves the record out. 


ie LESS THAN and LESS EQUAL operators work in a similar manner. The 
18S EQUAL operator includes a record if a field value is either less than or 
ual to the value expression specified. 


ie BETWEEN operator is the equivalent of the GREATER EQUAL and 

21SS_ EQUAL operators combined. It searches for records with field values that 
2 within the range specified or equal to either of the value expressions that 
termine the range. In the following example. the Boolean expression identifies 
ecord stream that includes records with values for SALARY of $30,000 and 
4,000: 


t> PRINT PERSONNEL WITH SALARY BETWEEN 30000 AND 54000 


FIRST LAST START SUP 
) . STATUS NAME NAME DEPT DATE SALARY ID 
343 TRAINEE JEFF TASHKENT C82  4-Apr-1981 $32,918 87465 
156 TRAINEE HANK MORRISON T32 1-Mar-1982 $30,000 87289 
162 EXPERIENCED BILL SWAY T32 5-May-1980 $54,000 00012 
973 TRAINEE SY KELLER T32  2-Aug-1981 $31,546 87289 
)01 EXPERIENCED DAN ROBERTS C82. 77-Jul-1979 $41,395 87465 
23 EXPERIENCED LYDIA HARRISON Fii 19-Jun-1979 $40,747 00891 
764 EXPERIENCED JIM MEADER T32 4-Apr-1980 $41,029 87289 
)01 EXPERIENCED DAVID LITELLA G20 11-Nov-1980 $34,933 87289 
342 EXPERIENCED BRUNO DONCHIKOV C82. 9-Aug-1978 $35,952 87465 
)29 EXPERIENCED RANDY PODERESIAN C82 24-May-1979 $33,738 87465 


Oo additional relational operators that separate records according to ranges are 
1FORE and AFTER. These operators are useful for comparing values for date 
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fields. BEFORE can be used interchangeably with LESS THAN, and AFTER car. 
be substituted for GREATER THAN. For example: 


DTR> PRINT PERSONNEL WITH START_DATE AFTER "1-Jan-1981" 


FIRST LAST START SUP 

ID STATUS NAME NAME DEPT DATE SALARY ID 
12643 TRAINEE JEFF TASHKENT C82 4-Apr-1981 $32,918 87465 
32432 TRAINEE THOMAS SCHWEIK Fii 77-Nov-1981 $26,723 00891 
34456 TRAINEE HANK MORRISON 132 1-Mar-1982 $30,000 87289 
48573 TRAINEE SY KELLER T32 2-Aug-1981 $31,546 87289 
49843 TRAINEE BART HAMMER D98 4-Aug-1981 $26,392 39485 
87701 TRAINEE NATHANIEL CHONTZ Fi1 28-Jan-1982 $24,502 00891 


91023 TRAINEE STAN WITTGEN G20 23-Dec-1981 $25,023 87289 


DTR> 


This query finds all employees who started after January 1, 1981. If there had 
been an employee who started on that date, the record would not have been 
included. 


2.3.3 Grouping Records Based on a MISSING VALUE 


If a missing value for a field is defined in the record definition using the 
MISSING VALUE JS field definition clause, you can search for records that 
_ either have or do not have the missing value. 


For example, in the PERSONNEL domain, a MISSING VALUE clause has been 
included in the record definition of the SUP ID field. That missing value is set as 
zero. You can form an RSE that asks DATATRIEVE to search for any records 
containing the MISSING VALUE: 


DTR> FIND PERSONNEL WITH SUP_ID MISSING 
{[O records found] 


You can also ask DATATRIEVE to search for records in which a field does not 
contain the MISSING VALUE you specified in the record definition: 


DTR> FIND PERSONNEL WITH SUP_ID NOT MISSING 
[23 records found] 
DTR> 
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!.4 Grouping Records by Reference to a Table 


me domains are associated with domain or dictionary tables that refer to one of 
> fields in the record. You can form an RSE that causes DATATRIEVE to look 


the field value in the table. If the field value is in the table. DATATRIEVE 
ludes the record in the record stream. An example of a table-based RSE is: 


tSONNEL WITH SUP_ID IN SUP_TABLE 


cords with supervisor identification numbers in the SUP TABLE are included 
the record stream. 


5 Summary of the Relational Operators 


ble 2-1 summarizes all of the relational operators available to form Boolean 
oressions in the WITH clause of an RSE. 


ble 2-1: Conditional Comparisons for an RSE 


Type of Relationship of Relational 

omparison | Values in Boolean Operator Boolean Expression 
Pattern Exact match (case- = BUILDER = “ALBIN” 
ecognition | sensitive). EQUAL “ALBIN” = BUILDER 


No match (case- 
sensitive). 


Substring matches 
(not case- 
sensitive). 


Beginning 
substring matches 
(case-sensitive). 


EQ 


NE 
NOT_EQUAL 


| NOTEQUAL 


CONT 
CONTAINING 


STARTING WITH 


BUILDER NE “ALBIN” 
“ALBIN” NE BUILDER 


BUILDER CONT “bin” 


BUILDER STARTING 
WITH “AL” 





(continued on next page) 
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Table 2-1: Conditional Comparisons for an RSE (Cont.) 


Type of Relationship of Relational 
Comparison | Values in Boolean Operator 


Value Within | First value is > 
a Range greater. GT 
GREATER_THAN 















Boolean Expression 









PRICE > 50000 
50000 > PRICE 











Date field value 
is later than the 
value expression. 


AFTER START_DATE AFTER 


“1-Jan-1981” 

















GE 
GREATER_ EQUAL 


PRICE GE 50000 
50000 GE PRICE 


First value is 
greater than or 
equal. 










PRICE < 20000 
20000 < PRICE 


< 
LT 
LESS_THAN 


First value is 
less. 









1 Date field value 
is earlier than 
the value 
expression. 


BEFORE START_DATE BEFORE 


“11-Jan-1981” . 







LE 
LESS_EQUAL 


BT 
BETWEEN 


First value is 


PRICE LE 20000 
less than or equal. 



















PRICE BETWEEN 30000 
AND 54000 


First value is 
between the two 
values or equal 
to one. 


Field Value | Field value is the MISSING 
Missing MISSING VALUE. 
Look Up in | Field value is in IN table-name 

Table the table. 


2.3.6 Setting Up Multiple Tests with Compound Booleans 





PRICE MISSING 







RIG IN RIG_ TABLE 


To set up multiple tests for records, you can join two or more Boolean expres- 
sions. The expressions that join Boolean expressions are called Boolean operator 


There are four Boolean operators: 


AND OR NOT BUT 
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sing AND, OR, and BUT, you can join two or more Boolean expressions to form 
single Boolean expression. NOT allows you to reverse the value of a Boolean 
pression. 


you link Boolean expressions with AND or BUT, the resulting Boolean expres- 
yn is true only if all the Boolean expressions linked with AND or BUT are true. 


you link Boolean expressions with OR, the resulting Boolean expression is true 
any one of the Boolean expressions linked with OR is true. 


you precede a Boolean expression with NOT, the resulting Boolean expression 
true if the Boolean expression following NOT is false. The reverse is also true: 
e resulting Boolean expression is false if the Boolean expression following NOT 
true. 


1e following examples show the use of Boolean operators: 


R> PRINT PERSONNEL WITH START_DATE BEFORE "1-Jan-1979" AND 
N> SALARY LT 36000 


FIRST LAST START _ SUP 
D STATUS - NAME NAME DEPT DATE SALARY ID 
342 EXPERIENCED BRUNO DONCHIKOV C82 9-Aug-1978 $35,952 87465 


1e first query shows that Bruno Donchikov is the only employee who started 
fore January 1, 1979 and is earning less than $36,000. 


R> PRINT PERSONNEL WITH DEPT = "TOP" OR SALARY > 54000 


FIRST LAST TART SUP 
D STATUS NAME. . NAME DEPT DATE SALARY ID 
012 EXPERIENCED CHARLOTTE SPIVA TOP 12-Sep-1972 $75,892 00012 
891 EXPERIENCED FRED HOWL Fil 9-Apr-1976 $59,594 00012 
485 EXPERIENCED DEE TERRICK D98 2-May-1977 $55,829 00012 
475 EXPERIENCED GAIL CASSIDY E46 2-May-1978 $55,407 00012 
375 EXPERIENCED MARY NALEVO D98 3-Jan-1976 $56,847 39485 
289 EXPERIENCED LOUISE DEPALMA G20 28-Feb-1979 $57,598 00012 


465 EXPERIENCED ANTHONY IACOBONE C82 2-Jan-1973 $58,462 00012 
R> 


1e second query displays data on all employees who are either in the TOP 
‘partment or earning more than $54,000. 


Writing Record Selection Expressions 2-13 


DTR> PRINT PERSONNEL WITH SALARY > 54000 BUT DEPT = "TOP" 


FIRST LAST START SUP 
ID STATUS NAME NAME DEPT DATE SALARY ID 
00012 EXPERIENCED CHARLOTTE SPIVA TOP 12-Sep-1972 $75 ,892 00012 


DTR> 


The third query displays data on all employees who earn more than $54,000 but 
who also are in the department TOP. 


2.4 Joining Records from Two or More Sources 


RSEs let you work with records from different sources. The CROSS clause of th 
RSE lets you form record streams by combining data from two or more sources 
records. It forms temporary relationships between records stored in different da 
files based on the relationship between field values in the different files. Joining 
records with the CROSS clause allows you to treat the data as though it derived 
from one data file. 


With the CROSS clause, you can: 


e Combine records from several domains, collections, or both. 
e Compare and combine records from one domain. 


e Substitute a single statement for nested FOR loops when comparing 
records. 


e Flatten hierarchical domains to ease access to the items in hierarchical lists 
Chapter 6 discusses hierarchical domains. 
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[his is the format of the RSE containing the CROSS clause: 


FIRST n [context-var IN] rse-source 
ALL | 


‘CROSS [context-var IN] rse-source [OVER field-name]] [...] 


WITH boolean-expression] [REDUCED TO reduce-key [,...]] 
SORTED BY sort-key ,...]] 


The format for rse-source is: 


domain-name 

collection-name 

list 

rdb-relation-name 

dbms-record-name MEMBER 
OWNER [OF] [context-name.set-name] 
WITHIN 


2.4.1 Using CROSS to Combine Two Domains 


Suppose you want to find the prices of individual boats in the YACHTS domain 
shat belong to boat owners stored in the OWNERS domain. You want to combine 
JWNERS records with YACHTS records that have the same MODEL and 
MANUFACTURER. The RSE that forms this temporary combination of records 
s on the second input line of the following PRINT statement. The group field 
['YPE, which includes both MANUFACTURER and MODEL, is the primary key 
‘or the YACHT.DAT file. It is defined as NO DUP; as a result, no two boats can 
1ave the same value for TYPE. 
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DTR> PRINT NAME, TYPE, PRICE OF 
CON> YACHTS CROSS OWNERS OVER TYPE 


NAME MANUFACTURER MODEL PRICE 
STEVE ALBIN VEGA $18 ,600 
HUGH ALBIN VEGA $18 , 600 
JIM C&C CORVETTE 
ANN C&C CORVETTE 
JIM ISLANDER BAHAMA $6 , 500 
ANN ISLANDER BAHAMA $6 ,500 
STEVE ISLANDER BAHAMA $6 , 500 
HARVEY ISLANDER BAHAMA $6 ,500 
TOM PEARSON 10M 
DICK PEARSON 26 
JOHN RHODES SWIF TSURE 
DTR> 


The OVER TYPE phrase takes the place of WITH OWNERS.TYPE = 
YACHTS.TYPE. This RSE forms a record stream of 11 records. 


2.4.2 Joining Records from Collections Based on the Same Domain 


In many cases, you will want to combine and compare records from the same 
domain. For instance, you may want to find those yachts built by different build- 
ers but with the same kind of rigging, or you may want to find any trainees who 
make more than experienced employees. In crosses like these, you must distin- 
guish separate record selection expressions that refer to the same domain. 
DATATRIEVE provides several ways to perform such crosses. One way is to use 
an alias to rename a domain. This operation temporarily creates two domains 
from one so you can ready and join them as if they were two separate sources. 


When you use the CROSS clause to form and combine two collections from the 
same domain, you must establish context for both collections. In order for 
DATATRIEVE to join records from collections based on a single domain, you 
must ready the domain twice, once using an alias. DEEENIEE: DATATRIEVE does 
not include records from both sources in the join. 


This example shows what happens when you ready YACHTS once, form two col- 
lections, AMERICAN YACHTS and ALBIN YACHTS, and join the collections 
with a CROSS clause: 


DTR> READY YACHTS . 
DTR> FIND AMERICAN_YACHTS IN YACHTS WITH BUILDER = 


"AMERICAN" 
[2 records found] 
DIR> FIND ALBIN _YACHTS IN YACHTS WITH BUILDER = "ALBIN" 


[3 records found] 


(continued on next page) 
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R> LIST AMERICAN_YACHTS CROSS ALBIN_YACHTS OVER RIG 


NUFACTURER : ALBIN 
DEL : 79 

G : SLOOP 
NGTH_OVER_ALL : 26 
SPLACEMENT 4,200 
AM : 10 

ICE : $17,900 
NUFACTURER : ALBIN 
DEL : 79 

G : SLOOP 
NGTH_OVER_ALL .: 26 
SPLACEMENT : | 4,200 
AM : 10 


ICE : $17,900 


ATATRIEVE does not include the records with BUILDER = “ AMERICAN “in 
e join. 


you ready the source domain twice, once under an alias, DATATRIEVE cor- 
ctly joins the records from both sources. In the following example, | 
ATATRIEVE treats each collection as though it originated from a different 
main: 


R> READY YACHTS, YACHTS AS EXTRA 
R> FIND AMERICAN_YACHTS IN YACHTS WITH BUILDER = "AMERICAN" 


records found] 


R> FIND ALBIN_YACHTS IN EXTRA WITH BUILDER = "ALBIN" 


records found] 


R> LIST AMERICAN_YACHTS CROSS ALBIN_YACHTS OVER RIG 


NUFACTURER : AMERICAN 
DEL : 26 

G : SLOOP 
NGTH_OVER_ALL : 26 
SPLACEMENT : 4,000 
AM ; 08 

ICE : $9,895 
NUFACTURER : ALBIN 
DEL : 79 

G : SLOOP 
NGTH_OVER_ALL : 26 
SPLACEMENT : 4,200 
AM : 10 

ICE : $17,900 
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If at any time you forget how you have used an alias, use the SHOW READY 
command to see the domain name behind the alias. For example: 


DTR> READY YACHTS, YACHTS AS EXTRA 
DTR> SHOW READY 
Ready sources: 
EXTRA: Domain, RMS sequential, protected read 
<CDD$TOP . DTR$LIB . DEMO. YACHTS; 1> 
YACHTS: Domain, RMS sequential, protected read 
<CDD$TOP. DTR$LIB . DEMO. YACHTS; 1> 
No loaded tables. 


2.4.3 Using CROSS to Cross a Domain with Itself 


Another way to compare and combine records from the same source is to use 
either the CROSS clause (without aliases), nested FOR loops, or view domains. 
See the FOR statement section in the VAX DATATRIEVE Reference Manual 
for more information about nested FOR loops. View domains are discussed in th 
views chapter in this book. This section explains how to use CROSS to compare 
records from the same domain. 


Consider the question of how to find the yachts whose manufacturers make boat 
with more than one type of rigging. To do this, you need to loop through the 
YACHTS domain twice. First, you must search through all yachts and group 
them by manufacturer. Then. you must search through these collections to find 
those yachts with different riggings. 


You can cross and compare the necessary record streams in a single RSE contai 
ing a CROSS clause: 


DTR> PRINT BUILDER, A.RIG, RIG OF A IN YACHTS CROSS 
Looking for name of domain, collection, or list] 
CON> YACHTS OVER BUILDER WITH A.RIG GT RIG 


MANUFACTURER RIG RIG 


AMERICAN SLOOP MS 

CHALLENGER SLOOP KETCH 
CHALLENGER SLOOP KETCH 
GRAMPIAN SLOOP KETCH 


PEARSON SLOOP KETCH 
DTR> 


The variable A (A IN YACHTS) is called a context variable. A context variable i 
a temporary name that identifies a record stream to DATATRIEVE . See 
Chapter 9 for an extended discussion of how to use context variables. Appendix 
contains detailed information about how DATATRIEVE establishes and inter- 
prets context variables. 
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1 the above example, DATATRIEVE establishes two sources, one called A IN 
ACHTS and the other called YACHTS. The OVER clause controls the compari- 
yn of records from the two sources. For each record from the source A IN 
ACHTS, DATATRIEVE retrieves only the records from the source YACHTS 
iat have the same BUILDER value as the record from A IN YACHTS. The 
oolean expression WITH A.RIG GT RIG selects from the record stream the 
airs of records that have different values for RIG. The resulting record stream 
yntains information only about builders who make more than one type of rig. 


ou could use the Boolean expression WITH A.RIG NE RIG to select the records 
ith two different RIG values. But if you use NE instead of GR. you get two com- 
nations for every pair of records that meet the criteria of the RSE. Using the 

T operator eliminates this duplication. 


ne advantage this method has over nested FOR loops is that the statement with 
1e CROSS clause is shorter than an equivalent statement with a FOR loop. (The 
vo methods take approximately the same amount of time to process.) 


.5 Finding the Unique Field Values in the Record Stream 


requently, a record stream contains several records that have the same values 
r a specific field. To find the unique field values (that is, to eliminate duplicate 
eld values from the record stream), use the REDUCED TO clause of the RSE. 


p to this point, the RSE clauses have let you limit the number of records in the 
‘cord stream. The REDUCED TO clause of the RSE lets you limit the fields 
ithin each record in the record stream. 


or example, if you want to know the name of all of the departments in the 
ERSONNEL domain, you can use this query: 


"R> FIND PERSONNEL REDUCED TO DEPT 
’ records found 
"R> PRINT CURRENT 


IPT 


32 
8 
6 
1 
0 
2 
)P 


o process the RSE, DATATRIEVE searches the values for DEPT and finds 
ven unique values. DATATRIEVE then generates a collection of seven records 
ith values for the DEPT field only. 


ometimes you want to know all the unique combinations of values for several 
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fields in the record. To find the combinations of values for DEPT and STATUS, 
use the RSE “PERSONNEL REDUCED TO DEPT, STATUS”: 


DTR> FIND PERSONNEL REDUCED TO DEPT, STATUS 
[12 records found] 


DTR> PRINT CURRENT 
DEPT STATUS 


C82 EXPERIENCED 
C82 TRAINEE 
D98 EXPERIENCED 
D98 TRAINEE 
E46 EXPERIENCED 
Fil EXPERIENCED 
Fii TRAINEE 
G20 EXPERIENCED 
G20 TRAINEE 
T32 EXPERIENCED 
T32 TRAINEE 
TOP EXPERIENCED 


DATATRIEVE finds 12 unique combinations of values and forms a collection wit 
12 records. Each record in the collection has values for only two fields, DEPT anc 
STATUS. 


The REDUCED TO clause is a powerful tool for forming relational queries. For 
example, the following query uses two RSEs to display the names of all the supe: 
visors and the departments they manage: 


DTR> FOR A IN PERSONNEL REDUCED TO SUP_ID 
[Looking for statement] 


CON> PRINT DEPT, NAME, ID OF PERSONNEL WITH ID = A.SUP_ID 


FIRST LAST 
DEPT NAME NAME ID 
TOP CHARLOTTE SPIVA 00012 
Fil FRED HOWL 00891 
D98 DEE TERRICK 39485 
E46 GAIL CASSIDY 48475 
G20 LOUISE DEPALMA 87289 


C82 ANTHONY IACOBONE 87465 
DTR> 


This query finds every employee who is a supervisor, that is, whose ID equals 
one of the values specified by the REDUCED TO clause. The RSE “A IN 
PERSONNEL REDUCED TO SUP ID” asks DATATRIEVE to develop a 
record stream (A) with all of the supervisor IDs. Then for each supervisor ID, . 
DATATRIEVE searches through all the PERSONNEL records again for matche 
on the ID field. When DATATRIEVE finds a match, it displays the ID. NAME, 
and DEPT of the employee. 
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o do this, the RSE must include a context variable, A, to refer to the SUP ID of 
1e first record stream. The context variable is then used in the Boolean expres- 
on ID = A.SUP ID. If you used the Boolean expression ID = SUP ID, 
\ATATRIEVE would consider SUP ID to be a field in the records of the second 
xcord stream. DATATRIEVE would then find all employees whose personal ID is 
1e same as their supervisor’s ID. (That is, all employees who supervise them- 
2lves.) The value expression A.SUP ID unambiguously refers to a field value 

‘om records in the first record stream. See Chapter 9 and Appendix A for more 
formation about context variables. 


.6 Sorting the Record Stream by Field Values 


Then you use a PRINT statement to display a record stream, the order of the 
cords is determined by the keys defined for the data file. However, you can use 
1e SORTED BY clause of the RSE to impose a different sort order on the record 
ream. 


or example, the records in PERSONNEL are already sorted by ID, the. primary 
2y for the data file. But if you are interested in the employees for each depart- 
lent, you can sort the records by DEPT. To break down each department into 
<perienced workers and trainees, specify STATUS as an additional sort key. The 
lowing query sorts the first nine PERSONNEL records according to DEPT and 
TATUS: 


[R> PRINT FIRST 9 PERSONNEL SORTED BY DEPT, STATUS 


FIRST LAST START SUP 
(D STATUS NAME NAME DEPT DATE SALARY ID 
'465 EXPERIENCED ANTHONY ITACOBONE C82 2-Jan-1973 $58,462 00012 
1342 EXPERIENCED BRUNO DONCHIKOV C82 9-Aug-1978 $35,952 87465 
1029 EXPERIENCED RANDY PODERESIAN C82 24-May-1979 $33,738 87465 
1001. EXPERIENCED DAN ROBERTS C82 = 7-Jul-1979 $41,395 87465 
1643 TRAINEE JEFF TASHKENT C82 4-Apr-1981 $32,918 87465 
1943 EXPERIENCED CASS TERRY D98 2-Jan-1980 $29,908 39485 
1485 EXPERIENCED DEE TERRICK D98 2-May-1977 $55,829 00012 
[375 EXPERIENCED MARY NALEVO D98 3-Jan-1976 $56,847 39485 
1843 TRAINEE BART HAMMER D98 = 44-Aug-1981 $26,392 39485 
"R> 


he SORTED BY clause overrides the order of the records in the data file. but it 
yes not change the physical order of the records in the data file. 


ou can also sort a record stream according to a value expression based on a field 
ilue. For example, you could sort by the year of START DATE by using the 
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value expression FNSYEAR (START DATE) as a sort key: 


DTR> READY PERSONNEL 

DTR> FIND FIRST 9 PERSONNEL SORTED BY FN$YEAR (START_DATE) 
DTR> PRINT ID, NAME, SALARY, 

CON> (FN$YEAR (START_DATE)) ("EMPLOYED"/"SINCE") USING 9999 


FIRST LAST EMPLOYED 

ID NAME NAME SALARY SINCE 
00012 CHARLOTTE SPIVA $75,892 1972 
87465 ANTHONY IACOBONE $58,462 1973 
84375 MARY NALEVO $56,847 1976 
00891 FRED HOWL $59,594 1976 
39485 DEE TERRICK $55,829 1977 
48475 GAIL CASSIDY $55 , 407 1978 
90342 BRUNO DONCHIKOV $35,952 1978 
99029 RANDY PODERESIAN $33,738 1979 
87289 LOUISE DEPALMA $57,598 1979 


DTR> 


The SORTED BY clause lets you produce reports with data records divided into 
groups. In the last example, using the value expression FN$YEAR 

(START DATE) as a sort key lets you report on employees grouped by the year 
they were first employed. For more information on creating such control group 
reports, see the VAX DATATRIEVE Guide to Writing Reports. For information 
on DATATRIEVE functions such as FN$YEAR, see the VAX DATATRIEVE 
Reference Manual. 
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Entering New Data 3 


his chapter explains how to enter new data in RMS domains using the STORE 
atement, prompting value expressions, and the TAB key. In addition, refer to 
ie following chapters for advanced topics: 


Using Forms with DATATRIEVE -- for information on storing data with 
forms . 


Using DATATRIEVE with DBMS -- for information on storing data in 
DBMS databases 


Using DATATRIEVE with Rdb -- for information on storing data in Rdb 
databases ; 


1 Using the STORE Statement | 


ju can create a record in the data file with the STORE statement. You can also 
ie the STORE statement to assign values to fields. When you enter a STORE 
atement followed by a domain name, DATATRIEVE prompts you for the values 
each field in the record. If you enter a field list or the USING clause, 
ATATRIEVE prompts you to enter only the specified fields. DATATRIEVE 

‘es not prompt you to enter REDEFINES or COMPUTED BY fields. 


R> READY OWNERS WRITE<RET> 

R> STORE OWNERS<RET> 

ter NAME: BILL<RET> 

ter BOAT_NAME: GLOOM<RET> 

ter BUILDER: DOWN EAST<RET> 

ter MODEL: 32T<RET> 

R> FIND OWNERS WITH BOAT_NAME = "GLOOM"<RET> 
record found] 


3-1 


DTR> SELECT; PRINT<RET> 


BOAT 
NAME NAME BUILDER MODEL 


BILL GLOOM DOWN EAST 32T 


DTR> 


When you respond to a DATATRIEVE prompt, you must supply a value, a space, 
or a TAB character, not a value expression. You cannot supply the name of a vari- 
able or a field and expect DATATRIEVE to use the value associated with the 
variable or the value associated with the field. DATATRIEVE interprets the name 
in either case as a character string literal and uses the literal as the value when 
making the assignment. 


3.2 The Effect of TAB on Prompts from STORE Statements 
If you respond with a TAB and RETURN to a prompt from a STORE statement: 


e If the field has a default value specified in its field definition, DATATRIEVE 
uses the default value to initialize the field. . 


e Ifthe field has a missing value but not a default value specified in its field 
definition, DATATRIEVE uses the missing value to initialize the field. 


e Ifthe field has a default value and a missing value specified in its field defini 
tion, DATATRIEVE uses the default value to initialize the field. 


e Ifthe field has neither a default value nor a missing value specified in its 
field definition. DATATRIEVE initializes numeric fields as 0 and alphabetic 
and alphanumeric fields as spaces. 


3.3 Using Direct Assignments 


With the USING clause of the STORE statement, you can limit the number of 
fields to which you assign new values. In the USING clause, you specify only 
those fields you want to change. 


When you store values in the fields of a new record with the USING clause of a 
STORE statement, DATATRIEVE uses the values you assign to initialize the 
fields specified in the USING clause. To initialize the fields that you do not 
include in the USING clause, DATATRIEVE takes one of three actions: 


e Ifa field has a default value specified in its field definition. DATATRIEVE 
uses the default value to initialize the field. whether or not there is also a 
missing value specified. 
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If a field has a missing value but not a default value specified in its field defi- 
nition, DATATRIEVE uses the missing value to initialize the field. 


If a field has neither a DEFAULT VALUE clause nor a MISSING VALUE 
clause, DATATRIEVE initializes the field with spaces if it is alphabetic or 


alphanumeric or with 0 if it is numeric. 


lis example shows the different actions DATATRIEVE takes when you assign a 
1ited number of values with the USING clause of a STORE statement: 


R> SHOW TEST_1<RET> 


MAIN TEST_1 USING TEST_REC ON TEST1.DAT;<RET> 


R> SHOW TEST_REC<RET> 
CORD TEST_REC USING 


TOP 


03 
03 
03 
03 
03 
03 
03 
03 


. 


DEF_VAL1 PIC X(7) 


DEFAULT VALUE IS "DEFAULT". 


MISS_VAL1 PIC X(7) 


MISSING VALUE IS "MISSING". 


BOTH_1 PIC X(7) 
DEFAULT VALUE IS "DEFAULT" 


MISSING VALUE IS "MISSING". 


NEITHER_STR PIC X(3). 
NEITHER_NUM PIC 999. 
DEF_VAL2 PIC X(7) 


DEFAULT VALUE IS "DEFAULT". 


MISS_VAL2 PIC X(7 


) 
MISSING VALUE IS "MISSING". 


BOTH_2 PIC X(7) 
DEFAULT VALUE IS "DEFAULT" 


MISSING VALUE IS "MISSING". 


%> READY TEST_1 WRITE<RET> 
t> STORE TEST_1-USING<RET> 
»oking for statement] 

Y> BEGIN<RET> 

»oking for statement] 


\> 


|> 


~DEF_VAL1 = "ONE"<RET> 
MISS_VAL1 = "TWO"<RET> 
BOTH_1 = "THREE"<RET> 


I> END<RET> 
~> FIND TEST_1<RET> 
record found] 


(continued on next page) 
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DTR> PRINT ALL<RET> 


DEF MISS BOTH NEITHER NEITHER DEF MISS BOTH 
VAL1 VAL1 1 STR NUM VAL2 VAL2 2 
ONE TWO THREE 000 DEFAULT MISSING DEFAULT 


DTR> STORE TEST_1<RET> 

Enter DEF_VALi: FOUR<RET> 

Enter MISS_VAL1: FIVE<RET> 

Enter BOTH_1: SIX<RET> 

Enter NEITHER_STR: <TAB><RET> 

Enter NEITHER_NUM: <TAB><RET> 

Enter DEF_VAL2: <TAB><RET> 

Enter MISS_VAL2: <TAB><RET> 

Enter BOTH_2: <TAB><RET> 

DTR> FIND TEST_1;SELECT LAST; PRINT<RET> 


DEF MISS BOTH NEITHER NEITHER DEF MISS BOTH 
VAL1 VAL1 1 STR NUM VAL2 VAL2 2 
FOUR FIVE SIX 000 DEFAULT MISSING DEFAULT 
DTR> 


3.4 Using Prompting Expressions in STORE Statements 


In the USING clauses of STORE, you can use prompting value expressions to 
control your input to records in data files. You can use two forms of prompting 
value expressions: *.prompt and **.prompt. These value expressions let you con: 
trol DATATRIEVE prompts for input. 


Both forms of prompting value expressions require you to respond by entering 
values, not value expressions. You cannot enter the names of variables or fields, 
and you cannot enter expressions from DATATRIEVE tables or arithmetic. sta- 
tistical, or concatenated expressions. You must enter numeric or character string 
literals appropriate to the data type of the field for which you are supplying a 
value. Do not enclose character string literals in quotation marks when you supp 
a value to a prompt. If you do, DATATRIEVE treats the quotation marks as par 
of the value. 


If a *.prompt is part of a USING clause in a STORE statement, DATATRIEVE 
prompts you for a value each time it executes the statement. If the STORE stat 
ment is in a REPEAT, FOR, or WHILE loop, DATATRIEVE prompts you each 
time it executes the loop. 
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‘a ** prompt is part of a USING clause in a STORE statement and if the 
TORE statement is ina REPEAT, FOR, or WHILE loop, DATATRIEVE 
rompts you only once, regardless of how many times it executes the loop. The 

* prompt is useful for assigning one value to a number of records when you have 
) assign unique values to other fields in each of those records. The following 
xample shows the difference between the two types of prompting valu 
xpressions: 


[R> SET NO PROMPT 
TR> READY PHONES WRITE 
[R> REPEAT 2 


JN> 
JN> 
JN> 
JN> 
JN> 
JN> 


JN> - 


iter 
iter 
iter 
iter 
iter 
iter 
[R> 


STORE PHONES USING 
BEGIN 
DEPARTMENT = **.DEPARTMENT 
LOCATION = **.LOCATION 
NAME = *«.NAME 
NUMBER = *.NUMBER 
END 
DEPARTMENT: CED<RET> 
LOCATION: MK3<RET> 
NAME: Gardens, Marvin<RET> 
NUMBER: 555-1776<RET> 
NAME: D’Ecor, Espree<RET> 
NUMBER: 555-1812<RET> 
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‘his chapter explains how to use the MODIFY statement to change data in exist- 
ig records. In addition, refer to the following chapters for advanced topics: 


Using Hierarchies -- for information on modifying records with repeating 
fields (fields defined with an OCCURS clause in the record definition) 


Using Forms with DATATRIEVE -- for supplementary information on modi- 
fying data with forms 


Using DATATRIEVE with DBMS -- for supplementary information on 
modifying data stored in DBMS databases 


Using DATATRIEVE with Rdb -- for supplementary information on modify- 
ing data stored in Rdb databases 


he MODIFY statement has the following formats: 
ormat | 
IODIFY [ALL] fisldcnaine [,..-] 
USING statement-1 
[VERIFY [USING] statement-2] 
[OF rse] 
erin 2 
IODIFY [ALL] rse 
USING statement-1 


[VERIFY [USING] statement-2] 
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When you modify records, you must ready the associated domain for modify or 
write access. Then perform the following five steps: 


¢ Decide on a record source (domain or collection). 

e Specify the records you want from the record source. 
e Specify the fields whose values you want to change. 
e Assign new values to those fields. 


e Optionally, specify any validation requirements that are not part of the 
record definition. 


The order of these steps may be the easiest and most logical, but keep in mind 
that when you write the DATATRIEVE statements that carry out a modify 
operation. the order in which you specify the logical steps can vary. | 
DATATRIEVE also lets you choose among alternative methods to accomplish the 
same logical step. In addition, you do not have to include syntax for all the steps 
in the MODIFY statement itself. 


This abundance of alternatives can be confusing when you first start to use 
DATATRIEVE. If you always think about DATATRIEVE syntax and examples 
in terms of which statement or clause accomplishes which logical step, you will 
find it easier to write the statements best suited to what you want to do. 


The following examples illustrate some of the ways to modify data. The text pre- 
ceding each example describes the objective of the modify operation. Comments 
to the right of the DATATRIEVE input lines identify the logical steps in the 
modify operation. In the first two examples, the NO PROMPT setting is in effect 
so DATATRIEVE’s "Looking for...” prompts do not appear. These informational 
prompts do not affect the outcome of the statements and commands you enter. 


e Change one DEPT value in the PERSONNEL domain. In this case, you 
work with records directly from the domain and change all records contain- 
ing the value. Note that you specify the record source and the record you 
want in the MODIFY statement itself: 


DTR> READY PERSONNEL MODIFY 
DTR> PRINT LAST_NAME, DEPT OF PERSONNEL WITH DEPT = "F11i" 


LAST 
NAME DEPT 
HOWL Fii 


SCHWEIK Fil 
HARRISON F111 
CHONTZ Fil 
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DTR> MODIFY PERSONNEL - ! <--- Specify record source 
CON> WITH DEPT = "F1i" ! <--- Select records 

CON> USING DEPT = ! <--- Specify field 
! 


CON> "F12" <--- Assign value 

DTR> 

DTR> PRINT LAST_NAME, DEPT OF PERSONNEL WITH DEPT = "F12" 
LAST 
NAME DEPT 

HOWL Fi2 


SCHWEIK F12 
HARRISON F12 
CHONTZ F12 


Modify the price of one record in YACHTS. Because you are working with a 
selected record from the CURRENT collection, you specify in the MODIFY 
statement only the name of the field you want to change: 


DTR> READY YACHTS MODIFY 

DTR> FIND YACHTS_WITH BUILDER = "ALBIN" 

{3 records found] 

DTR> PRINT MANUFACTURER, MODEL, PRICE 

No record selected, printing whole collection. 


MANUFACTURER MODEL PRICE 

ALBIN 79 $17,900 

ALBIN BALLAD $27 ,500 

ALBIN VEGA $18,600 

DTR> SELECT 3 . ; 

DTR> MODIFY PRICE ! <--- Specify field 
Enter PRICE: 20,000 ! <--- Assign new value 
DTR> 
DTR> PRINT MANUFACTURER, MODEL, PRICE OF CURRENT 
MANUFACTURER MODEL PRICE 

ALBIN 79 $17,900 

ALBIN BALLAD $27 ,500 

ALBIN VEGA $20,000 
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e Modify the records of all yachts manufactured by Albin to reflect a 10 
percent price increase. Because you are working with the CURRENT collec- 
tion, you do not include the name of the record source in the MODIFY state- 
ment itself. You do, however, include the keyword ALL in the MODIFY 
statement so that DATATRIEVE knows you are not modifying a selected 
record: 


DTR> READY YACHTS MODIFY 

DTR> FIND YACHTS WITH BUILDER = "ALBIN" 

[3 records found} 

DTR> PRINT MANUFACTURER, MODEL, PRICE 

No record selected, printing whole collection. 


MANUFACTURER MODEL PRICE 

ALBIN 79 $17,900 

ALBIN BALLAD $27 ,500 

ALBIN VEGA $18,600 

DTR> MODIFY ALL - ! <--- Specify records 
[Looking for statement] teat 

CON> USING PRICE = ! <--- Specify field 
[Looking for value expression] ; 

CON> PRICE * 1.1 ! <--- Assign values 


DTR> 
DTR> PRINT MANUFACTURER, MODEL, PRICE OF CURRENT 


MANUFACTURER BEAM PRICE 
ALBIN 79 $19,690 
ALBIN BALLAD $30, 250 
ALBIN VEGA $20 , 460 

DTR> 


As you can see, DATATRIEVE gives you a great deal of flexibility when you 
modify records. You can write statements so that DATATRIEVE prompts you to 
enter values for the fields you want to change, or you can specify field values 
directly. Your MODIFY statement can process records in an RSE, or it can 
default to the CURRENT collection. 


The following sections explain: 


e Modifying records in a collection 
e Modifying records in a record selection expression 


e Avoiding common mistakes in modifying records 
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Using DATATRIEVE prompts when modifying data 
Checking for valid values in the MODIFY statement 


ote that the optional clause VERIFY [USING] validation-statement clause is 
cluded in all syntax formats so that you can determine where you include that 
ause in the MODIFY statement. Section 4.5 discusses what the VERIFY clause 
n contain and provides examples of its use. 


ote also that no matter what form of the MODIFY statement you choose, you 
nnot modify the value of an index key field that has been defined so that 
langes are not allowed. For example, you can never modify the value of a field 
at is the primary key for an indexed data file. 


1. Modifying Records in the CURRENT Collection 


wrming a collection and then using that collection as the record source for a 
odify operation is generally easier than trying to include the record selection 
ntax in the same DATATRIEVE statement that specifies fields and assigns 
lues. The FIND statement forming the collection specifies the record source 

id does most of the work to select the records you want. You can then simply 
pe PRINT ALL and press the RETURN key to check the contents of the entire 
llection before and after the modify operation. You can also select a record and 
en type PRINT and press RETURN to display the same information for a par- 
‘ular record. 


Note 


While it may be easier to use a collection as a record source, 
DATATRIEVE generally works slower when retrieving records from 
collections. For more information on optimizing DATATRIEVE que- 
ries, see the chapter on improving performance in this manual. See 
Chapter 14 of the VAX DATATRIEVE Handbook for a discussion of 
the advantages and disadvantages of using collections. 


1.1. Modifying a Selected Record in the CURRENT Collection 


‘ter you form a collection and display the records it contains, use the SELECT 
atement to pick the record to be modified. SELECT 1 specifies the first record 
splayed, SELECT 2 specifies the second record displayed. and so forth. After 

u enter your SELECT statement, print the results to make sure you have the 
cord you want. If you discover you picked the wrong record, you can enter 
SLECT NONE and reenter a SELECT statement with a corrected record occur- 
nee value. 
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You have a choice of the following formats to modify the selected record: 


MODIFY [VERIFY [USING] validation-statement] 


DATATRIEVE prompts once for each elementary field in the record definition 
and changes the field values to the ones you enter. You can simply type MODIFY 
and press the RETURN key, and DATATRIEVE gives you the opportunity to 
change each field in the selected record. 


MODIFY field [,...] [VERIFY [USING] validation-statement] 


DATATRIEVE prompts once for each elementary field that you name and once 
for each elementary field that is subordinate to each group field that you name. 
The values of those fields are changed to the ones you enter. For example. if you 
want to change only LAST NAME and ZIP in a PERSONNEL record, you can 
enter MODIFY LAST. NAME. ZIP. Then DATATRIEVE prompts you only for 
those fields. 


MODIFY USING assignment-statement 
[VERIFY [USING] validation-statement] 


The assignment statement in the USING clause may be a series of PRINT and 
assignment statements that you include in a BEGIN-END block. 


If you name an elementary field in an assignment statement, DATATRIEVE 
changes its value to the one you specify. For example: 


ae MODIFY USING FIRST_NAME = "CASSANDRA" 
> 


If you name a group field, DATATRIEVE gives you an error message stating 
“illegal assignment to a group field.” 


You are prompted to enter a value for a field only when the assignment statemer. 
contains a prompting value expression for the field value. 


FIND list-field 
SELECT n 
MODIFY item-field [VERIFY [USING] validation-statement] 


Use this format to modify fields subordinate to a field defined with an OCCURS 
clause in a record definition or a view definition. The chapter on using hierarchie: 
describes this format in detail. 
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IDIFY [ALL] list-item OF list 


‘e this format to modify all occurrences of fields subordinate to a field defined 
th an OCCURS clause in a record definition or a view definition. The chapter on 
ing hierarchies describes this format in detail. 


1.2 Modifying All Records in the CURRENT Collection 


you want to change values in all the records of the CURRENT collection, you 
ve the choice of the following formats: 


IDIFY ALL [VERIFY [USING] validation-statement] 


\TATRIEVE prompts you once for each field in the record definition. The val- 
s you enter for fields change those fields in every record in the collection. Use 
s format with care when your collection contains more than one record. Rarely 
you want to make every field in every record identical. 


DIFY ALL field [,...] [VERIFY [USING] validation-statement] 


\TATRIEVE prompts once for each elementary item specified or implied by the 
ld name or names you specify. The values you enter for fields change those 
Ids in every record in the collection. 


ie this format with care when the CURRENT collection contains more than one 
cord. If you enter the statement MODIFY ALL LAST NAME and respond to 
\TATRIEVE’s prompt by entering SMITH, every record in the CURRENT col- 
tion then contains SMITH in the LAST NAME field. You use this format only 
change values that you want to be identical among records in the collection. 

r example, you might want to modify a field like SUPERVISOR ID in a collec- 
n of records for employees that share the same supervisor. 


IDIFY ALL USING assignment-statement 
[VERIFY [USING] validation-statement] 


e€ assignment statement in this format can be a series of PRINT and assign- 
nt statements ina BEGIN-END block. 


you name an elementary field in an assignment statement. DATATRIEVE 
anges its value in every record in the collection. If you name a group field, 
\TATRIEVE changes the value of each elementary field in the group in every 
‘ord in the collection. 


u are prompted to enter a value for a field only when the assignment statement 
1tains a prompting value expression. 
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This format of the MODIFY statement has the same effect as the preceding for- 
mat. For example, if you enter the statement MODIFY ALL USING 

LAST NAME = "SMITH". every record in the CURRENT collection contains 
SMITH in the LAST NAME field. 


4.2 Modifying All Records in a Record Selection Expression 


The previous section showed that when you work with the CURRENT collection 
or a selected record. the MODIFY statement does not need to contain a record 
source or which particular records to modify. You can display records and change 
values using relatively few keystrokes. 


When you do not want the MODIFY statement to assume a CURRENT collectic 
or a selected record for the modify operation, you have to specify both the record 
source and exactly which records you want to change as an RSE. You must. 
include the RSE either in the MODIFY statement itself or in the FOR statemen 
component of a compound statement that also includes the MODIFY statement. 
If you plan for a display of records before and after the modify operation (defi- 
nitely a good idea), you must include PRINT statements as well. 


Modifying records in an RSE is the best method to use when writing procedures. 
Usually procedures contain compound statements, and you cannot use the 
DATATRIEVE statements that create and manipulate collections in compound 
statements. Writing compound statements that modify data is not difficult if you 
keep in mind the logical steps to a modify operation and make sure you include a 
of them in the statements you form. 


4.2.1 Modifying Records Controlled by a FOR Statement 


The FOR statement lets you modify each record in a record stream. The FOR 
statement creates a stream of records that are processed, one by one, by the nex 
statement. In a modify operation, that next statement can be either a MODIFY 
statement or a BEGIN-END block that includes a MODIFY statement. 


You can choose among the following formats: 


FOR rse MODIFY [VERIFY [USING] validation-statement] 


DATATRIEVE prompts once for every elementary field in the record definition 
for each record in the record stream. In short. you can individually change all thi 
fields in every record. 


For example. if you enter FOR YACHTS WITH BUILDER = "ALBIN” 
MODIFY, you can change every field in every record that a Albin as the 
manufacturer. 
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DR rse MODIFY field [,...] 
[VERIFY [USING] validation-statement] 


ATATRIEVE prompts once for each elementary field that you name and once 
r each elementary field that is subordinate to each group field that you name in 
ie MODIFY statement. You can change every record, but only the fields 
ecified. 


you enter FOR YACHTS WITH BUILDER = “ALBIN” MODIFY PRICE, for 
‘ample, you can change only the price field in every record that species Albin 
: the manufacturer. 


DR rse MODIFY USING statement 
[VERIFY [USING] validation-statement] 


1e statement in the USING clause can be a BEGIN-END block that contains 

e PRINT and assignment statements you want DATATRIEVE to apply to each 
cord in the record stream. DATATRIEVE changes values in every record for as 
any fields as have assignment statements. DATATRIEVE does not prompt for 
dues unless you include prompting value expressions in the assignment 
atements. 


1e following statement uses this format: 


R PERSONNEL WITH ID = EMPLOYEE_VARIABLE 
MODIFY USING 
BEGIN 
PRINT ID, EMPLOYEE_NAME, DEPT, SUP_ID, SKIP 
FIRST_NAME = *."first name (all caps) or TAB character" 
LAST_NAME = * "last name (all gana) or TAB character" 
DEPT = * . "department code (all caps) or TAB character" 


SUP_ID = *."supervisor ID number or TAB character" 
PRINT SKIP, ID, EMPLOYEE_NAME, DEPT, SUP_ID 
END 


1e FOR rse limits the record stream to the record that has an ID field matching 
e contents of a variable called EMPLOYEE VARIABLE. The statements inside 
e BEGIN-END block within the USING clause do three things: 

Print the values of the fields that are being changed 


Prompt the user to modify only certain fields of the record 


Print the new values of the fields that were modified 
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The procedure FOR RSE MODIFY, which includes this statement, uses 
EMPLOYEE VARIABLE to check that the user entered an existing employee 
ID: 


DTR> SHOW FOR_RSE_MODIFY 
PROCEDURE FOR_RSE_MODIFY 
SET ABORT 
DECLARE EMPLOYEE_VARIABLE PIC 9(5). 
EMPLOYEE_VARIABLE = *."employee ID number" 
WHILE NOT ANY PERSONNEL WITH ID = EMPLOYEE_VARIABLE 
BEGIN 
PRINT SKIP 
PRINT "Invalid employee number." 
DECLARE GET_OUT PIC X(5). 
GET_OUT = *."any letter if you want to stop, TAB to try again" 
IF GET_OUT NOT = "" THEN 
ABORT "Exit from procedure" ELSE 
EMPLOYEE_VARIABLE = *."employee ID number" 
END 
READY PERSONNEL MODIFY 
SET NO ABORT 
FOR PERSONNEL WITH ID = EMPLOYEE_VARIABLE 
MODIFY USING 
BEGIN 
PRINT ID, EMPLOYEE_NAME, DEPT, SUP_ID, SKIP 
FIRST_NAME = *."first name (all caps) or TAB character" 
LAST_NAME = *."last name (all Gane) or TAB character" 
DEPT = *."department code (all caps) or TAB character" 
SUP_ID = *."supervisor ID number or TAB character" 
PRINT SKIP, ID, EMPLOYEE_NAME, DEPT, SUP_ID 
END 
FINISH PERSONNEL 
END_PROCEDURE 


DTR> 


See the chapter on using procedures in this manual and the VAX DATATRIEVI 
Handbook for information on procedures and compound statements. 


FOR rse MODIFY list-rse USING 
assignment-statement [VERIFY [USING] validation-statement] 


FOR rse FOR list-rse MODIFY [field-name [,...] ] 
[VERIFY [USING] validation-statement] 


You can use these two formats to change the values of records with repeating 
fields. See the chapter on using hierarchies for more information. 


If you include the CURRENT collection as the RSE in a FOR statement. you car 
easily display all the records that are changed by simply entering PRINT ALL. 
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his is useful when the RSE that gathers the records to be modified can no longer 
ate them after the modify operation. 


‘ you do specify a collection as the record source in a FOR statement, keep in 
1ind that DATATRIEVE cannot do keyed retrieval on a collection. When you are 
orking with a large collection, therefore, the FOR statement should not attempt 
) limit further the records being processed (FOR CURRENT WITH ANY... is 

ne example). If it does, DATATRIEVE could process the modification more 
owly for each record than when it can use collection records in sequential order. 
0 optimize performance when you specify a collection as the record source in a 
OR statement, have the FIND statement that forms the collection do all the 
xcord selection work. | 


efer to the chapter on improving DATATRIEVE performance for more detailed 
formation about improving DATATRIEVE’s response time. 


.2.2 Including the RSE Within the MODIFY Statement 


i1cluding the records to be modified as part of the MODIFY statement is some- 
hat trickier than specifying the same information in FIND, FIND and SELECT, 
- FOR statements. Depending on what you want to do, you must specify the 

SE immediately after the keyword MODIFY (or MODIFY ALL), or you must 
rite the RSE at the end of the statement. It is, therefore, easier to make syntax 
‘rors when you try to include an RSE in the MODIFY statement. 


ou should not include an RSE within a MODIFY statement that changes hierar- 
1ical records (records that contain a list field or records from a view domain that 
>cesses more than one simple domain). If you do, DATATRIEVE may trap you 

| an endless loop of ”Re-enter” prompts for the repeating field values. 


ou cannot specify different field values for each record in the MODIFY state- 
lent RSE as you can when you modify records using a FOR statement RSE. The 
[ODIFY statement RSE means you supply only one value for each elementary 
eld you specify by name or imply with a group field name. The value you enter 
yplies to every record. Therefore. make sure you specify records that should con- 
iin identical values for the field or fields you are changing. 


eeping these cautions in mind, you can choose among the following formats: 
ODIFY [ALL] [VERIFY [USING] validation-statement] OF rse 


‘se with care. If you simply enter a domain name, you can make every record in 
1e domain identical. 
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MODIFY [ALL] field [,...] 
[VERIFY [USING] validation-statement] OF rse 


MODIFY [ALL] rse USING 
assignment-statement [VERIFY [USING] validation-statemen 


MODIFY [ALL] USING 
assignment-statement [VERIFY [USING] validation- -statement!] 
OF rse 


The assignment statement in these formats can also be a series of assignment 
and PRINT statements ina BEGIN-END block. 


4.3 Common Context Errors 


Sections 4.1 and 4.2 contain the correct formats to modify the records you want 
to change from the record source you intend to use. This section describes some 
problems you can encounter if you inadvertently use the wrong format or combin: 
format elements incorrectly. When you make this kind of mistake, 
DATATRIEVE either displays an error message or modifies records from the 
wrong record source, depending on the type of error you make. 


4.3.1. Modifying All Records Rather Than Just the Selected Record 


If you want to modify a selected record, do not include the keyword ALL in the 
MODIFY statement. 


If you type MODIFY ALL, you are telling DATATRIEVE either to target the 
entire collection for the modify operation or to expect an RSE in the MODIFY 
“statement. Because there may be times when this is your intention. 
DATATRIEVE does not display an error message. If you create this situation 
unintentionally, you can make all the records in the CURRENT collection identi- 
cal for the field values you supply when you intended to change values in only ont 
of those records. | 


4.3.2 Modifying the Wrong Selected Record 


This error can occur if you forget to enter a SELECT statement for the 
CURRENT collection. There may be times when you have more than one collec- 
tion in your workspace, and the collections formed before the CURRENT one 
have selected records. When you enter a MODIFY statement appropriate for a 
selected record and your CURRENT collection does not have one, DATATRIEV] 
tries to apply the modify operation to the selected records you do have available. 
It modifies the most recently selected record to which it can apply your state- 
ment. If your statement contains a field name that is not in any of the available 
selected records. DATATRIEVE does not modify any record but tells you that tk 
field name is used out of context. 
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1ere may be times when you want to modify a selected record in a collection 

her than the CURRENT one. In this case, you can enter SELECT NONE 
atements to “unselect” records associated with any collections formed after the 
te containing the selected record you want to change. In effect, this process 
leases selected records from the currect collection, and you can repeat it until 
ru reach the individual records selected from the target collection. 


1e error you want to avoid in this situation is entering too many or too few 
ELECT NONE statements. You can use the PRINT statement to see which is 
e current selected record. You can also use SHOW CURRENT or SHOW 
OLLECTIONS to make sure that you are working with the collection you want. 


3.3 Modifying Records in the Wrong RSE 


1is error occurs when you intend to modify records using a FOR statement 
SE, but you also intentionally include an RSE or the keyword ALL in the 
ODIFY statement itself. If you do this, you are telling DATATRIEVE to 
odify records specified in the MODIFY statement for as many iterations as 
ere are records in the FOR statement RSE. (The only time you want to do 
mething like this is when you modify repeating fields in a hierarchical record. 
hen you modify hierarchical records, however, the RSE in the MODIFY state- 
ent specifies an OCCURS field name as the record source, rather than a true 
cord source, such as a domain or collection.) If you inadvertently include two 
SEs in the combined statements that carry out a modify operation, the results 
n be unexpected. 


the following example, the user intends to change the last name in the first 
LRSONNEL record. The superfluous RSE in the FOR statement causes 
ATATRIEVE to prompt for the field as many times as there are records in the 
SRSONNEL domain: 


R> SET NO PROMPT 
R> FOR PERSONNEL MODIFY FIRST 1 PERSONNEL USING BEGIN 


N> PRINT 
N> LAST_NAME = *."last name" 
N> END 

FIRST LAST START SUP 
D STATUS NAME NAME DEPT DATE SALARY ID 
012 EXPERIENCED CHARLOTTE SPIVA TOP 12-Sep-1972 $75,892 00012 
ter last name: WHITE is 
012 EXPERIENCED CHARLOTTE WHITE TOP 12-Sep-1972 $75,892 00012 
ter last name: <TAB> 
012 EXPERIENCED CHARLOTTE WHITE TOP 12-Sep-1972 $75,892 00012 
ter last name: <TAB> 


012 EXPERIENCED CHARLOTTE WHITE TOP 12-Sep-1972 $75,892 00012 
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A correct statement in the previous example, would have been either: 


MODIFY FIRST 1 PERSONNEL USING . 


or 


FOR FIRST 1 PERSONNEL MODIFY USING . 


In the following example, the user intends to modify the DEPT field of only the 
employee record with ID number 34456. Because of the keyword ALL in the 
MODIFY statement, however, DATATRIEVE uses the value entered to modify 
the DEPT field of all the records in the CURRENT collection: 


DTR> FIND PERSONNEL WITH DEPT = "T32" 

[4 records found] 

DTR> 

No record selected, printing whole collection. 


FIRST LAST START SUP 


ID STATUS NAME NAME DEPT DATE SALARY ID 
34456 TRAINEE HANK MORRISON 132 1-Mar-1982 $30,000 87289 
38462 EXPERIENCED BILL SWAY T32  5-May-1980 $54,000 00012 
48573 TRAINEE SY KELLER T32  2-Aug-1981 $31,546 87289 
83764 EXPERIENCED JIM MEADER T32  4-Apr-1980 $41,029 87289 


DTR> FOR PERSONNEL WITH ID = 34456 
CON> MODIFY ALL DEPT 


Enter DEPT: Fii 
DTR> PRINT 


No record selected, printing whole collection. 


FIRST LAST START SUP 

ID STATUS NAME NAME DEPT — DATE SALARY ID 
34456 TRAINEE HANK MORRISON Fi1i 1-Mar-1982 $30,000 87289. 
38462 EXPERIENCED BILL SWAY Fil 5-May-1980 $54,000 00012 
48573 TRAINEE SY KELLER Fii 2-Aug-1981 $31,546 87289 
83764 EXPERIENCED JIM MEADER Fil 4-Apr-1980 $41,029 87289 
DTR> ! YIPES!!!! 
DTR> 


To avoid this, the user could enter either: 


SELECT 1; MODIFY DEPT 


or 


FOR PERSONNEL WITH ID = 34456 MODIFY DEPT 
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|.4 Using DATATRIEVE Prompts | 
“here are two ways you can get DATATRIEVE to prompt you for values: 


Using forms of the MODIFY statement that do not require a USING clause 


Including a prompting value expression in the Assignment statements within 
the USING clause (for example. USING LAST NAME = *."last name”) 


Javing DATATRIEVE prompt you to enter values has the following advantages: 


You do not have to type in all the Assignment statements. 


If you enter an invalid value or one that is too large for the field. 
DATATRIEVE displays an error message and reprompts so you can try 
again. 


You do not have to enter nonnumeric values in quotation marks. In fact, 
DATATRIEVE treats quotation marks as part of the value, so you should 
not use them unless they are actually part of the field value. 


If you press TAB and then the RETURN key in response to a prompt for a 
field value, DATATRIEVE leaves the value of the field unchanged, regard- 
less of any DEFAULT or MISSING values defined for the field. This can be 
useful if you are prompted to enter values for fields you decide not to 
change. 


' Tf you respond with CTRL/Z to a prompt for a field value, DATATRIEVE 
does not change any field in the record you are currently changing. This is 
useful if you realize you made a mistake entering earlier values for that 
record. 


Remember, however, that entering CTRL/Z does not affect records you have 
finished modifying, only the one you are working with when you enter 
CTRL/Z. CTRL/Z also aborts the statement being executed. This means, for 
example, that if your statement is processing ten records and you enter 
CTRL/Z while modifying the fifth record, you do not get a chance to modify 
the remaining five records. You must reenter the statement to modify the 
fifth through tenth records. 


Jsing prompting value expressions within the USING clause of a MODIFY state- 
nent is a very flexible method for assigning values to fields. 
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In the following example, the double asterisk prompts mean that the user is 
prompted to enter one field value that applies to all the records in the collection. 
The single asterisk prompts mean that the user is prompted to enter a field value 
for each record: 


DTR> SET NO PROMPT 

DTR> READY YACHTS MODIFY 

DTR> FIND YACHTS WITH BEAM = 0 
[5 records found] 

DTR> FOR CURRENT MODIFY USING 
CON> BEGIN 

CON> PRINT SPECS 

CON> LOA = **.LOA 

CON> DISP * WEIGHT 
CON> BEAM * ._BEAM 

CON> PRICE = PRICE * 1.1 
CON> END 


LENGTH 
OVER 
ALL 


RIG WEIGHT BEAM PRICE 


SLOOP 32 
Enter LOA: 33 
Enter WEIGHT: 
Enter BEAM: 10 
SLOOP 32 
Enter 
Enter 


9,500 00 
12000 


.11,000 00 


$29,500 
: <TAB><RET> . 


SLOOP 31 
Enter 
Enter BEAM: 
SLOOP 35 
Enter 
Enter BEAM: 
SLOOP 32 
Enter 
Enter 


WEIGHT: 
12 


WEIGHT: 
13 


WEIGHT: 
BEAM: 9 


13,600 00 
15000 


23,200 00 
<TAB><RET> 


14,900 00 
<TAB><RET> 


DTR> PRINT ALL 


MANUFACTURER 


METALMAST 
0’ DAY 
RYDER 

TA CHTAO 
WRIGHT 


DTR> 


MODEL RIG 


GALAXY SLOOP 
32 SLOOP 
S. CROSS SLOOP 
FANTASIA SLOOP 
SEAWIND II SLOOP 


$32,500 


$34,480 


LENGTH 


OVER 


_ALL 


WEIGHT BEAM 


12,000 10 
11,000 11 
15,000 12 
23,200 13 
14,900 09 


PRICE 


$32,450 
$35,750 


$37 ,928 


You must respond to a prompt with a value rather than a value expression. 
For example. if you want to increase a price field by ten percent and let 
DATATRIEVE do the calculation, you must use direct assignment. 
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IATATRIEVE will not let you enter PRICE * 1.1 in response to a prompt. If you 
re writing a procedure that needs this flexibility, you can prompt for part of the 
alue expression. For example, you can prompt for the price increase and include 
1e arithmetic calculation of the new value for PRICE in your Assignment state- 
1ent (PRICE = PRICE * *.” price increase”). 


.5 Ensuring Valid Values 


\ATATRIEVE always checks the record definition that applies to the record you 
re changing to ensure that new field values have the correct length and data 

ype. It also applies any VALID IF clauses in the record definition to the changed 
eld values. DATATRIEVE displays an error message and leaves the existing 
eld value untouched if a modify operation tries to enter a value that the record 
efinition does not allow. 


he VERIFY clause of the MODIFY statement lets you supplement the valida- 
on requirements in the record definition. It can also help you enforce security 
leasures for modification procedures. 


he format of the VERIFY clause is: 
ERIFY [USING] validation-statement 


he validation statement can be a series of statements within a BEGIN-END 
lock. 


he VERIFY clause in the following example ensures that the first and last 
ames entered for an employee begin with a capital letter: 


[TR> FOR PERSONNEL WITH ID = *."ID number for record being changed" 
IN> MODIFY VERIFY USING 


JN> BEGIN 

JN> WHILE FIRST_ NAME NOT BT "A" AND "Z" 

JN> BEGIN 

JN> PRINT SKIP, “Invalid first name" 

JN> FIRST_NAME = *."first name using CAPS" 
JN> END 

JN> WHILE LAST_NAME NOT BT "A" AND "Z" 

JN> BEGIN 

JN> PRINT SKIP, "Invalid last name" 

JN> LAST_NAME = *."last name using CAPS" 
JN> END 

JN> END 


lote that DATATRIEVE does all verification only after all the data is entered for 
1e record being modified. 
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Using View Domains 5 


(his chapter introduces the concept of view domains. 


\ view is a special type of domain that lets you select some (or all) fields in some 
or all) records from one or more domains. Using a view, you can refer to fields 
ind field values in different domains without duplicating their records or data. 


(ou define a view by creating a domain definition for it in the Common Data 
Jictionary (CDD). A view lets you read and modify selected field values. Because 
here is no data stored for a view, you cannot store or erase the records you 
etrieve with a view. Although you can combine records from various domains 
vith the CROSS clause of the RSE, a view is the only type of domain that you 
‘an define in the CDD for working with data in more than one domain. 


‘ou define a view with the DEFINE DOMAIN command. The format of the com- 
nand for defining a view is: 


JEFINE DOMAIN view-path-name OF domain-path-name-1 [,...] eae 


level-number-1 field-name-1 | OCCURS FOR rse-1 . 


OCCURS FOR rse-n 


level-number-2 field-name-2 FROM domain-path-name-n 





[FORM [IS] form-name [IN] form-library] 


\fter the keyword OF, you must list each domain that the view uses. You can 
pecify the domains in any order, separating them with commas. You must end 
‘ach field definition with a period and end the view definition with a semicolon. 
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You use two clauses to define the fields in a view: 


¢ OCCURS FOR 
e FROM 


The top-level field must be defined with an OCCURS FOR clause. The record 
selection expression in the first OCCURS FOR clause determines the number of 
records in the view. Each subsequent OCCURS FOR clause creates a list within 
the view. Consequently, a view that contains more than one OCCURS FOR 
clause is always a hierarchy. (The first OCCURS FOR clause does not make the 
view a hierarchy. It only establishes the source record stream for the view.) 


See Chapters 6 and 11 for a discussion of view domains that are hierarchies. 


You establish the fields of data for the view with the FROM clause. It specifies 
the name of the field and the domain from which it derives. The domain must be 
the same domain named in the previous OCCURS FOR clause. The field name 
must be either a field name or a query name from that domain. 


To ready a view, you must have the proper access privilege, and you must also 
have the same access privilege to the domain that the view uses. You ready a view 
domain directly; do not ready the domain that the view uses. 


The next section shows how to define a view that contains a subset of records in 
the YACHTS domain. It uses that view to illustrate some general properties of 
views. 


5.1 Views Using Subsets of Records 


A view lets you work with a specific subset of records from another domain. For 
instance, you may want to work with the records for ketches only and no other rig 
type. The following example shows a view definition that allows you to work with 
four fields of the yachts that are ketches: | 


DTR> DEFINE DOMAIN KETCHES 

DFN> OF YACHTS BY 

DFN> O01 KETCH OCCURS FOR YACHTS WITH RIG EQ "KETCH". 
DFN> 03 TYPE FROM YACHTS. 

DFN> 03 LOA FROM YACHTS. 

DFN> 03 PRICE FROM YACHTS. 

DFN> ; 

DTR> READY KETCHES 

DTR> PRINT FIRST 4 KETCHES 
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LENGTH 


OVER 
NUFACTURER MODEL ALL PRICE 
LBERG 37 MK II 37 $36,951 
HALLENGER 41 Al $51,228 
ISHER 30 30 
ISHER 37 37 


R> 


1e view domain KETCHES, which is based on the single domain YACHTS, is 
it hierarchical because there is only one OCCURS FOR clause. 


yu Cannot store or erase records in a view. Otherwise, you can use a view just as 
u would any other domain. For example: 


R> READY KETCHES MODIFY 

R> FIND KETCHES WITH PRICE EQ 0 
records found] 

R> PRINT ALL 


LENGTH 

OVER 
NUFACTURER MODEL ALL PRICE 
ISHER 30 30 
ISHER 37 37 
EARSON 365 36 
EARSON 419 42 


R> FOR CURRENT PRINT THEN MODIFY PRICE 


LENGTH 
OVER 

VUFACTURER MODEL ALL PRICE 
[SHER 30 30 
ter PRICE: $30,000 
[SHER 37 37 
ter PRICE: 45,000 
ZARSON 365 36 
ter PRICE: 32000 
ZARSON 419 42 


ter PRICE: 54000 


(continued on next page) 
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DTR> PRINT ALL 


LENGTH 

OVER 
MANUFACTURER MODEL ALL PRICE 
FISHER 30 30 $30 ,000 
FISHER 37 37 $45 ,000 
PEARSON 365 36 $32,000 
PEARSON 419 42 $54,000 


DTR> FINISH 
DTR> 


Views using a subset of records are also useful with DBMS domains and Rdb rel 
tions and domains. See Chapters 14 and 15 for information about DBMS and Rc 
views. 


5.2 Views Using Subsets of Fields 


One type of view lets you refer to a subset of fields from the records of another 
domain. For example. the record definition for YACHTS contains seven elemen- 
tary fields and three group fields: 


DTR> SHOW YACHT 
RECORD YACHT USING 
O01 BOAT. 

03 TYPE. 

O06 MANUFACTURER PIC X(10) 
QUERY_NAME IS BUILDER. 

06 MODEL PIC X(10). 

03 SPECIFICATIONS 

QUERY_NAME SPECS. 

06 RIG PIC X(6) 

VALID IF RIG EQ "SLOOP", "KETCH", "MS", "YAWL". 

06 LENGTH_OVER_ALL PIC XXX 
VALID IF LOA BETWEEN 15 AND 50 

-  QUERY_NAME IS LOA. 

06 DISPLACEMENT PIC 99999 
QUERY_HEADER IS "WEIGHT" 
EDIT_STRING IS ZZ,ZZ9 
QUERY_NAME IS DISP. 

06 BEAM PIC 99 MISSING VALUE IS 0. 

06 PRICE PIC 99999 
MISSING VALUE IS 0 
VALID IF PRICE>DISP*1.3 OR PRICE EQ 0 
EDIT_STRING IS $$$,$$$. 


DTR> 


If you want to work with only a few fields of the record, you can create a record 
definition for those fields and then create a domain and a data file containing on 
record for each record in YACHTS. The result is a data file that duplicates some 
field values in an existing data file (YACHT.DAT). Maintaining these two files s 
that they always contain the same field values would be difficult. 
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ou 
iat 
id 


can define a view, however, that lets you look at just the fields in YACHTS 
you need, without duplicating field values. You also avoid the additional time 
overhead of creating another record definition and creating and updating two 


ita files: 


‘R> DEFINE DOMAIN MAKERS 
‘N> OF YACHTS BY 

N> 01 BOAT OCCURS FOR YACHTS. 
N> 03 TYPE FROM YACHTS. 
ne 03 RIG FROM YACHTS. 

N> ; 

R> READY MAKERS 

R> PRINT FIRST 6 MAKERS 


NUFACTURER MODEL RIG 


LBERG 37 MK II KETCH 
LBIN 79 SLOOP 
LBIN BALLAD SLOOP 
LBIN VEGA SLOOP 
MERICAN 26 SLOOP 
MERICAN 26-MS MS 
AYFIELD 30/32 SLOOP 
LOCK I. 40 SLOOP 
OMBAY CLIPPER SLOOP 
UCCANEER 270 SLOOP 
R> 


3 Views Using More Than One Domain 


ie preceding sections showed how to use view domains to define a subset of 
cords or fields from a single domain. 


ews can also use more than one domain. There are two general ways different 
mains can be combined in a view: 


Combine record streams by using more than one OCCURS FOR clause. 
Each OCCURS FOR clause has its own RSE, and DATATRIEVE creates a 
hierarchical relationship between the record streams specified in each RSE. 


For example. the sample domain SAILBOATS uses two OCCURS FOR 
clauses to create a hierarchical relationship between two record streams: 


DTR> SHOW SAILBOATS 
DOMAIN SAILBOATS OF YACHTS, OWNERS USING 
01 SAILBOAT OCCURS FOR YACHTS. 
03 BOAT FROM YACHTS. 
03 SKIPPERS OCCURS FOR OWNERS WITH TYPE = BOAT.TYPE. 
OS NAME FROM OWNERS. 


DTR> 
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Chapter 6 discusses creating hierarchies with view domains in more detail. 


e Use a CROSS clause in the RSE of the OCCURS FOR clause to refer to 
more than one domain. The remainder of this section eASCUBSOS using the 
CROSS clause in a view domain. 


To illustrate how to use the CROSS clause in a view to combine records from 
more than one domain, look at the CROSS example in the chapter on using 
record selection expressions. Recall that this PRINT statement displays the 
NAME field from the OWNERS domain and the TYPE and PRICE fields from 
the corresponding records in the YACHTS domain: 


DTR> PRINT NAME, YACHTS.TYPE, PRICE OF YACHTS CROSS OWNERS OVER TYPE 


OWNER 

NAME MANUFACTURER MODEL PRICE 
STEVE ALBIN VEGA $18,600 
HUGH ALBIN VEGA $18 , 600 
JIM C&C CORVETTE 

ANN C&C CORVETTE 

JIM ISLANDER BAHAMA $6,500 
ANN ISLANDER BAHAMA $6 ,500 
STEVE ISLANDER BAHAMA $6 ,500 
HARVE ISLANDER BAHAMA $6 , 500 
TOM PEARSON 10M 

DICK PEARSON 26 

JOHN RHODES SWIFTSURE 

DTR> 


You can define a view domain, CROSS SAILBOATS, to get the same results: 


e Include the RSE YACHTS CROSS OWNERS OVER TYPE after the 
OCCURS FOR clause. 


e Specify the fields you want to include in the domain--NAME, TYPE. and 
PRICE--in the FROM clauses of the view domain. 


The following example shows the definition for CROSS SAILBOATS. It shows 
how a simple PRINT statement produces the same results as the previous PRIN 
statement that used the CROSS clause. 


DTR> SHOW CROSS_SAILBOATS 

DOMAIN CROSS_SAILBOATS OF YACHTS, OWNERS USING 

01 SAILBOAT OCCURS FOR YACHTS CROSS OWNERS OVER TYPE. 
03 NAME FROM OWNERS. 
03 TYPE FROM YACHTS. 
03 PRICE FROM YACHTS. 


DTR> READY CROSS_SAILBOATS 
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t> PRINT CROSS_SAILBOATS 


IER 
ME MANUFACTURER MODEL PRICE 
z ALBIN VEGA $18,600 
3H = ALBIN VEGA $18,600 
A c&c CORVETTE 

q c&c CORVETTE 

A ISLANDER BAHAMA $6 ,500 
q ISLANDER BAHAMA $6 ,500 
c ISLANDER BAHAMA $6 ,500 
tVE ISLANDER BAHAMA $6 , 500 
A PEARSON 10M 

3 PEARSON 26 

IN RHODES SWIFTSURE 

> 


4 Advantages and Disadvantages of Using Views 


ice you can define a view with any RSE that you might type interactively, view 
mains are convenient substitutes for typing complex record selection expres- 
ms you use often. 


.e of the greatest advantages of a view is that you can use it to combine fields 
mm an Rdb database with fields from RMS (file-structured) domains.and DBMS 
mains. You can have a single view that brings together data from these differ- 
t types of databases. 


view domain is also a convenient way to create a dynamic hierarchy. By using 

2 OCCURS FOR clause, you can create temporary list fields. You then have the 
ility to display data in hierarchical form without being tied to hierarchical 

‘ords for other tasks. 


a can also use a view to mask the data in certain fields from users who do not 
ed to see it. Select the fields you want the user to see from each underlying 
main and define a view that uses only those fields. However, because users 
ist also have access to the underlying domains, views cannot keep users from 
‘rieving sensitive data directly from those domains. 


le very important disadvantage of using views lies in the danger of modifying 
-ords from multiple sources. You must be careful when you modify values in a 
‘w based on more than one domain. If the field you are changing is stored in 
»re than one data file, you are updating only one of those files for each field 
lue you enter. 
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If the view refers to a second domain based on the value of a field in the first 
domain, a change to a field value in the first domain can cause DATATRIEVE t 
select an unexpected record from the second domain. When you use a form to 
modify such a view, the field value you see on the screen may not be the value y 
are actually modifying. See the chapter on forms in this book for an example of 
this problem in modifying a view. 


Observe the following cautions and restrictions when you use views that refer to 
more than one domain: 

e Try to avoid updating with a view. 

e Set up view domains that minimize duplicate fields. 


e Remember that when a view contains more than one OCCURS FOR rse ea 
OCCURS FOR rse after the first creates a list field. All the rules and restri 
tions for handling hierarchical data apply to those fields. 


¢ Do not modify a field in a view that uses the FORM IS clause when that fie 
forms the basis for selecting records from a second domain. (See the chapte 
on forms in this book for an example of this restriction.) 


5-8 Using View Domains 


Using Hierarchies 6 


DATATRIEVE, the term hierarchy refers to a one-to-many relationship — 
‘tween record sources. 


ith hierarchies, you can nest record streams to see a single record from one 
cord source displayed with a combination of records from another record source. 
1is nesting establishes a ” parent-child” relationship between the two record 
reams. For each record in the outer, “parent” record stream, you see all records 
the inner, “child” record stream. Parent records are displayed even if there are 
» corresponding child records in the inner record stream. 


yme examples of how this can be useful are: 


One team with several players 

One project with several workers 

One employee with several previous jobs 
One library with many books 

One computer with several users 


yy instance. a hierarchy could nest record streams from the YACHTS and 
WNERS domains. A parent-child relationship between YACHTS and OWNERS 
uld link the YACHTS record with a given make and model, ALBIN VEGA, say, 
th all OWNERS records that had the same make and model fields. 


ere is how DATATRIEVE displays such a hierarchy. It shows each YACHTS 
cord and a list of records from OWNERS of people who bought that make and 
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model boat. Note that the hierarchy includes the YACHTS record for a boat, eve 
if there are no corresponding records in the OWNERS domain: 


MANUFACTURER 


ALBERG 
ALBIN 
ALBIN 
ALBIN 


AMERICAN 
AMERICAN 
BAYFIELD 
BLOCK I. 
BOMBAY 
BUCCANEER 
BUCCANEER 
C&C 


CABOT 


MODEL 


37 MK II 
79 
BALLAD 
VEGA 


26 
26-MS 
30/32 
40 
CLIPPER 
270 


320 
CORVETTE 
36 


RIG 


KETCH 
SLOOP 
SLOOP 
SLOOP 


SLOOP 
MS 

SLOOP 
SLOOP 
SLOOP 
SLOOP 
SLOOP 
SLOOP 


SLOOP 


LENGTH 
OVER 
ALL 


OWNER 
WEIGHT BEAM PRICE NAME 


20,000 
4,200 
7,276 
5,070 


4,000 
5,500 
9,500 
18,500 
9,400 
5,000 
12,500 
8,650 


15,000 


$36,951 
$17 ,900 
$27,500 
$18,600 


$9,895 
$18,895 
$32,875 


$23 ,950 


BOAT 


STEVE DELIVERA 


HUGH IMPULSE 
JIM EGRET 
ANN EGRET 


The ability to nest record streams is a powerful feature of DATATRIEVE. By set 
ting up a parent-child relationship between record streams, you can see parent 
records whether or not there are any records in the child record stream. Using 
hierarchies is the only way to display records in this way. Joining YACHTS and 
OWNERS with a CROSS statement does not show the YACHTS records that d 
not have a corresponding records in the OWNERS domain: 


DTR> PRINT BOAT, NAME, BOAT_NAME OF YACHTS CROSS OWNERS OVER TYPE 


MANUFACTURER 


ALBIN 
ALBIN 
C&C 

C&C 
ISLANDER 
ISLANDER 
ISLANDER 
ISLANDER 
PEARSON 
PEARSON 
RHODES 


DTR> 


MODEL 


VEGA 
VEGA — 
CORVETTE 
CORVETTE 
BAHAMA 
BAHAMA 
BAHAMA 
BAHAMA 
10M 

26 

SWIF TSURE 
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RIG 


SLOOP 
SLOOP 
SLOOP 
SLOOP 
SLOOP 
SLOOP 
SLOOP 
SLOOP 
SLOOP 
SLOOP 
SLOOP 


LENGTH 
OVER 
ALL 


WEIGHT BEAM PRICE 


5,070 
5,070 
8,650 
8,650 
4,200 
4,200 
4,200 
4,200 


12,441 


5,400 
14,000 


$18,600 
$18,600 


$6,500 
$6 ,500 
$6 ,500 
$6 , 500 


OWNER 
NAME BOA’ 
STEVE DELIVER: 
HUGH IMPULSE 
JIM EGRET 
ANN EGRET 
JIM  POTEMKII 
ANN  POTEMKII 
STEVE POTEMKI! 
HARVE MANANA 
TOM LONE TR, 
DICK PURSUIT 
JOHN STRIDER 


ou can create a hierarchical relationship in two ways: 


Within a record definition by using the OCCURS clause to define a repeating 
field. DATATRIEVE sees repeating fields as an inner record within a record. 
Records with repeating fields are also called hierarchical records. 


Between different types of records by nesting record streams: 


% Hierarchical view domains 
- Inner print lists 


- Nested FOR statements 


Nesting record streams creates a hierarchy between nonhierarchical records. ° 
(Any records without repeating fields are nonhierarchical. They are also 
called “flat” records.) 


| Note 


Both methods let you show parent records with any and all child 
records. Creating hierarchies between flat records by nesting record 
streams is preferable because you can directly modify and retrieve data 
using the flat records. This avoids the complexities of accessing repeat- 
ing fields to modify and retrieve data, but lets you create hierarchies 
when you need their advantages. 


1is chapter describes: 


Defining records with repeating fields 
Retrieving values from repeating fields 
Modifying values stored in repeating fields 


Creating hierarchies from flat records by nesting record streams 
1 Defining Records with Repeating Fields 


»peating fields ina DATATRIEVE record definition are similar to fields defined 
th the OCCURS clause in COBOL and to one-dimensional arrays in BASIC. 
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When a record definition contains a repeating field, it means that there can be 
multiple occurrences of each field subordinate to the repeating field. In 
DATATRIEVE syntax, repeating fields are also called lists. Fields subordinate tc 
the list are called list items. . 


Retrieving data from repeating fields is not as easy as retrieving. data from other 
types of fields. For this reason. avoid using repeating fields when defining 
records. You can get the display advantages of repeating fields by nesting record 
streams from separate flat records. 


However. you may have to use repeating fields to define a record for a data file 
that already exists. Or. you may have to use an existing record that contains 
repeating fields. (See the chapter entitled Designing Better Records for informa- 
tion on restructuring a record with repeating fields into several flat records.) 


The examples on the following pages are based on the FAMILIES domain that is 
part of the VAX DATATRIEVE installation kit. The parent-child relationship 
common to all hierarchies is illustrated literally in the record definition for 
FAMILIES: for each record in FAMILIES, there is one set of parents to several 
children. 


Records without repeating fields are often called flat records because the elemen- 
tary fields in them are logically equivalent to each other. When you print a flat 
record, all the elementary fields are displayed in the order defined by the level 
numbers assigned to the fields. Figure 6-1 shows this logical equivalence imposec 
by the level numbers in the record definition YACHT. 










O1 BOAT 


03 TYPE 03 SPECIFICATIONS 
05 BUILDER | 05 MODEL O35 DISP | 05 BEAM 


Figure 6-1: A Flat Record: YACHT 







O35 PRI 


MK-01: 


You can define a flat record for information about a family. Each record contains 
the names of the father and mother and the names and ages of the number of 
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ids you pick as the maximum number for the record. The following sample 
xcord definition works for families with up to two kids: 


L FAMILY. 
03 PARENTS. 
O06 FATHER PIC X(10). 
06 MOTHER PIC X(10). 
03 KIDS. 
06 FIRST_KID. 
O09 KID_NAME PIC X(10). 
O09 AGE PIC 99 EDIT_STRING IS 29. 
06 SECOND_KID. 
O9 KID_NAME PIC X(10). 
O09 AGE PIC 99 EDIT_STRING IS 29. 


7hen you print a record with this definition, DATATRIEVE prints the field val- 
es in the following order: 


KID KID 
FATHER MOTHER NAME AGE NAME AGE 
NIE ANNE SCOTT 2 BRIAN 0 


he display generated by the flat record does not group the information about the 
ids in a way that suggests the parent-child relationship. In addition, the flat 
cord lets you store information about two kids only. A repeating field provides a 
ormat that groups the information to convey the list items are subordinate to the 
ther elementary fields in the record. It also lets you store information about 

10re than two kids. 


1 hierarchical records, the repeating field is equivalent to the other elementary 
elds with the same level number, and the list items are subordinate to the list. 
igure 6-2 shows this logical subordination of the list items to the list and the 
ther elementary fields in the FAMILY record. The record stores the same type 
f information for each of the kids, and each field containing that information is 
escribed only once in the record definition. The record itself, however, can con- 
iin many fields of the same description -- one set for each kid. 


‘xample 6-1 shows the actual record definition that corresponds to the logical 
tructure illustrated in Figure 6-2. 
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Q1 FAMILY 


03 PARENTS 03 NUMBER_KIDS | 03 KIDS OCCURS 1 TO 10 TIMES 
OG FATHER | 06 MOTHER ee See 06 EACH_KID 


O39 KID_NAME 09 AGE 
06 EACH_KID 


O9 KID-NAME O98 AGE 


+ ¢ 


OG EACH_KID 


O09 KID_NAME 09 AGE 


ZK-0003- 


Figure 6-2: A Hierarchical Record: FAMILY REC 


The OCCURS clause in the record definition is the key to the hierarchical struc- 
ture. Lists can be variable- or fixed-length, depending on the syntax of the 
OCCURS clause in the record definition. The list in the FAMILY record is a 
variable-length list: it repeats items a variable number of times according to a 
value stored in another record field (NUMBER KIDS). 


6.1.1 Defining Lists with a Fixed Number of Occurrences 


If you define a hierarchical record with a list that occurs a fixed number of times, 
every record in the domain contains enough space to store the same number of 
list items. The OCCURS clause format for fixed-length lists is OCCURS n 
TIMES. where n is the number of occurrences. 


You can use OCCURS n TIMES with an elementary or group field. A record defi- 
nition can contain any number of OCCURS clauses in this format, any place in 
the record. 


Using an OCCURS clause in a record definition eliminates the redundancy of 
defining the same fields for each kid and establishes the group field KIDS as a 
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st. This record definition uses a fixed-length list to provide a hierarchical struc- 
ire for the information about families with two kids: 


. FIXED_LENGTH_FAMILY. 
03 PARENTS. 
O06 FATHER PIC X(10). 
O6 MOTHER PIC X(10). 
03 KIDS OCCURS 2 TIMES. 
06 KID_NAME PIC X(10). 
06 AGE PIC 99 EDIT_STRING IS Z9. 


you define the record using OCCURS 2 TIMES. it is displayed in the following 
rmat: 


KID 
FATHER MOTHER NAME AGE 
tNIE ANNE SCOTT 2 
BRIAN 0 


his record definition causes the group field KIDS to repeat twice (OCCURS 2 
IMES) in each record. Each elementary field subordinate to KIDS repeats twice. 


1.2 Defining Lists with a Variable Number of Occurrences 


sing the OCCURS...DEPENDING clause in a field definition creates a hierar- 
1ical record that allows a variable number of list items from one record to 
10ther. This format lets you vary the number of list items in the records of a 
ymain: 


CCURS min TO max TIMES DEPENDING ON field-name 


ou can have only one field in a record definition with an 
CCURS...DEPENDING clause in this format. It must appear at the end of the 
cord definition, 


ach record in the sample FAMILIES domain contains the names of the parents, 
1e number of kids, and the name and age of each kid. The record definition for 
AMILIES uses the OCCURS...DEPENDING clause to define KIDS as a 
ariable-length list. The actual number of list items in a record depends on the 
alue of the NUMBER KIDS field. If the value is 0. the record contains no data 
sout kids. If the value of NUMBER KIDS is 1. the record contains data about 
1e kid, and so on. Each occurrence of the KIDS field contains the group field 
ACH KID. EACH KID in turn contains two elementary fields: KID NAME and 
GE. EACH KID is a group field in the list. Like other group fields. it allows you 
) refer to its subordinate fields with one name. (Note that DATATRIEVE does 
ot let you use the OCCURS field name as you would a group field name in your 
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statements. To DATATRIEVE, the OCCURS field name identifies what it sees a 
a record stream source within the record itself. For more information, see Sectior 
6.2.) 


Example 6-1 shows the record definition associated with FAMILIES. 


Example 6-1: The FAMILY Record Definition 


01 FAMILY. 
03 PARENTS. 
O06 FATHER PIC X(10). 
O06 MOTHER PIC X(i0). 
03 NUMBER_KIDS PIC 99 EDIT_STRING IS Z9. 
03 KIDS OCCURS O TO 10 TIMES DEPENDING ON NUMBER_KIDS. 
06 EACH_KID. 
O09 KID_NAME PIC X(10) QUERY_NAME IS KID. 
09 AGE PIC 99 EDIT_STRING IS 29. 


When you display the fields in FAMILIES, DATATRIEVE identifies the field 
KIDS as a list: 


DTR> SHOW FIELDS FAMILIES 
FAMILIES 
FAMILY 
PARENTS 
FATHER <Character string> 
MOTHER <Character string> 
NUMBER_KIDS <Number> 
KIDS <List> 
EACH_KID 
KID_NAME (KID) <Character string> 
AGE <Number> 


DTR> 


The output of the PRINT command shows the relationship between 

NUMBER KIDS and the fields KID NAME and AGE. Example 6-2 shows all 
the records in the FAMILIES domain. The values of KID NAME and AGE 
appear as a list in records with the number of kids greater than zero. 


Example 6-2: The Hierarchical Records in FAMILIES 
DTR> PRINT FAMILIES 


NUMBER KID 


FATHER MOTHER KIDS NAME AGE 
JIM ANN 2  URSULA 7 
RALPH 3 


(continued on next page) 
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xample 6-2: The Hierarchical Records in FAMILIES (Cont.) 


[M 


JHN 


JHN 
iNIE 


TEARMAN 
IM 


ASIL 


JB 
EROME 


OM 
EORGE 


AROLD 


DWIN 


TR> 


.1.3 Defining Sublists to Nest Lists Within Lists 


LOUISE 


JULIE 


ELLEN 
ANNE 


SARAH 
ANNE 


MERIDETH 


DIDI 
RUTH 


BETTY 


LOIS 


SARAH 


TRINITA 


5 


Nr bd 


Ne 


ANNE 
JIM 
ELLEN 
DAVID 
ROBERT 
ANN 
JEAN 


CHRISTOPHR 


SCOTT 
BRIAN 
DAVID 
PATRICK 
SUZIE 
BEAU 
BROOKS 
ROBIN 
JAY 
WREN 
JILL 


ERIC 
CISSY 
NANCY 
MICHAEL 
MARTHA 
TOM 
JEFF 
FRED 
LAURA 
CHARLIE 
HAROLD 
SARAH 
ERIC 
SCOTT 


31 


ilthough you can use only one OCCURS...DEPENDING clause in a record defi- 
ition, you can define any number of fixed-length lists within a variable-length 


st. 


‘he sample record definition PET REC is an extension of the FAMILY record 
hat illustrates sublists. The repeating field PET occurs twice for each kid, so 
ach kid in each family can record the data for two pets they own: 


TR> SHOW PETS 


OMAIN PETS USING PET_REC ON PET.DAT; 
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DTR> SHOW PET_REC 
RECORD PET_REC 
01 FAMILY. | 
03 PARENTS. 
O6 FATHER PIC X(1i0). 
O6 MOTHER PIC X(1i0). 
03 NUMBER_KIDS PIC 99 EDIT_STRING IS Z9. 
03 KIDS OCCURS O TO 10 TIMES DEPENDING ON NUMBER_KIDS. 
O06 EACH_KID. 
O09 KID_NAME PIC X(10) QUERY_NAME IS KID. 
09 KID_AGE PIC 99 EDIT_STRING IS Z9. 
09 PET OCCURS 2 TIMES. 
13. PET_NAME PIC X(1i0). 
13. PET_AGE PIC 99. 


. 
’ 


DTR> READY PETS 
DTR> PRINT FIRST 2 PETS 


NUMBER KID KID PET PET 


FATHER MOTHER KIDS NAME AGE NAME AGE 
JIM LORAINE 2 GARY 24 POP 03 
SODA 04 

SUE 23 MOUSE 03 

SHORTY 08 

JIM ANN 2  URSULA 7 SQUEEKY 03 
- FRANK 07 

RALPH 3 00 

. 00 


DTR> 


6.2 Retrieving Values from Repeating Fields 


When you retrieve a value from a record containing a repeating field, you cannot 
always apply the same statements you do for other records. The following 
sequence of statements shows what can happen when you try to print the repeat- 
ing field KIDS from the hierarchical record families: 


DTR> READY FAMILIES 
DTR> SHOW FAMILY_REC 
RECORD FAMILY_REC 
O1 FAMILY. 
03 PARENTS. 
06 FATHER PIC X(10). 
O06 MOTHER PIC X(10). 
03 NUMBER_KIDS PIC 99 EDIT_STRING IS Z9. 
03 KIDS OCCURS O TO 10 TIMES DEPENDING ON NUMBER_KIDS. 
06 EACH_KID. 
O09 KID_NAME PIC X(10) QUERY_NAME IS KID. 
O9 AGE PIC 99 EDIT_STRING IS 29. 
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"R> PRINT FATHER OF FAMILIES 
FATHER 


-M 
-M 


"R> PRINT MOTHER OF FAMILIES 
MOTHER 


IN 
lUISE 


'‘R> PRINT KIDS OF FAMILIES 
INT KIDS OF FAMILIES 


pected end of statement, encountered "OF". | 
‘R> 


ou can print the names of fathers and mothers successfully. But when you try to 
‘int the list field KIDS, you get an error message. If you form a collection, you 
n again print information on fathers and mothers but not kids: 


R> FIND FAMILIES 


3 records found] 
R> PRINT ALL FATHER 


FATHER 


M 
M 


R> PRINT ALL MOTHER 
MOTHER 


N 
UISE 


R> PRINT ALL EACH_KID 


ACH_KID" is undefined or used out of context 
R> PRINT ALL KIDS 


IDS" is undefined or used out of context 
R> PRINT ALL KIDS OF FAMILIES 
INT ALL KIDS OF FAMILIES 


pected end of statement, encountered "OF". 
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In the first two examples, you get a message stating that the field name is 
undefined or used out of context. The third example results in the same message 
you got in the previous example. To retrieve the information, you can apply one o 
the following methods to set up a DATATRIEVE context: 


e Use a FIND statement to establish a context for the list. Then use a 
SELECT statement to identify one record in the collection. 


e Use nested FOR rse loops. The outer FOR loop forms a target stream of 
hierarchical records and the inner FOR loop forms a stream of list items 
within a hierarchical record. 


e Use inner print lists (ALL print-list OF rse) to form a stream of list items 
within a record stream. 


The following sections describe these methods for retrieving items from lists. 


6.2.1 Retrieving Repeating Field Values with FIND and SELECT 


You use the FIND statement to find all the records in the file that meet your 
specifications. Then you can use the SELECT statement to request any one of 
these records: 


DTR> READY FAMILIES 
DTR> FIND FAMILIES 
[14 records found] 
DTR> SELECT 3; PRINT 


NUMBER KID 


FATHER MOTHER KIDS NAME AGE 
JOHN JULIE 2 ANN 29 
JEAN 26 


When you have selected a record that contains a list, you can treat the list as 
though it were a source of records like a domain or collection. You can continue 2 
follows: 


DTR> PRINT KIDS 


KID 

NAME AGE 
ANN 29 
JEAN 26 


You can also combine the FIND and SELECT statements to single out one list 
item. Then the context of the selected list item allows you to use the list item 
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ame by itself in a PRINT statement. Continue the previous example by forming 
collection of the KIDS list field and selecting a list item from the collection: 


"R> FIND KIDS 


’ records found] - 
"R> SELECT 2; PRINT 


KID 
NAME AGE 
“AN 26 


‘R> PRINT AGE 
iE 

) 

R> 


ou can use the same technique to get at nested repeating fields, such as the 
ET field in the hierarchical record PET REC: 


‘R> READY PETS 
R> SHOW PET_REC ! Here’s what the record for PETS looks like: 
‘CORD PET_REC 
FAMILY. 
03 PARENTS. 
O6 FATHER PIC X(10). 
O6 MOTHER PIC X(10). 
03 NUMBER_KIDS PIC 99 EDIT_STRING IS Z9. 
03 KIDS OCCURS O TO 10 TIMES DEPENDING ON NUMBER_KIDS. 
O06 EACH_KID. 
O09 KID_NAME PIC X(10) QUERY_NAME IS KID. 
O09 KID_AGE PIC 99 EDIT_STRING IS Z9. 
O9 PET. OCCURS 2 TIMES. 
13. PET_NAME PIC X(10). 
13 PET_AGE PIC 99. 


R> ! First, form a collection of the records in the PETS domain: 
R> FIND PETS 


records found] 
R> SELECT 3; PRINT 


NUMBER KID KID PET PET 
FATHER MOTHER KIDS NAME AGE NAME AGE 
M LOUISE 5 ANNE 31 FRANK 14 
FRANK 14 
JIM 29 00 
00 
ELLEN 26 00 
00 
DAVID 24 00 
00 
ROBERT 16 00 
00 
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DTR> ! Second, form a collection of the "records" in the 
DTR> ! KIDS repeating field: 

DTR> FIND KIDS 

[5 records found] 

DTR> SELECT 1; PRINT 


KID KID PET PET 

NAME AGE NAME AGE 
ANNE 31 FRANK 14 
FRANK 14 


DTR> ! Third, form a collection of the "records" 
DTR> ! in the PET repeating field: 

DTR> FIND PET 

[2 records found] 

DTR> ! Finally, you can print a field subordinate to 
DTR> ! the nested repeating field PET: 

DTR> SELECT 1; PRINT PET_AGE 


PET 
AGE 


14 


You cannot retrieve the value of repeating fields from more than one record using 
only FIND and SELECT statements. 


6.2.2 Retrieving Repeating Field Values with Nested FOR Loops 


To retrieve values from list items by nesting FOR loops, start from the top of the 
hierarchy and work toward the list items you want to retrieve. In the following 
example, the source for the RSE in the first or outer FOR loop is the hierarchical 
domain FAMILIES. The source in the second loop is the list item KIDS: 


DTR> FOR FAMILIES 

[Looking for statement] 
CON> FOR KIDS WITH AGE < 10 
[Looking for statement] 
CON> PRINT KID_NAME 


KID 
NAME 


URSULA 
RALPH 
CHRISTOPHR 
SCOTT 
BRIAN 
DAVID 
PATRICK 
SUZIE 


DTR> 
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1e FOR statement preceding the PRINT statement in the following example 
yps through all the records in FAMILIES. For each of those records, the RSE 
the PRINT statement retrieves only the first kid whose age is less than 10: 


R> FOR FAMILIES 
ooking for statement] 
N> PRINT KID_NAME OF FIRST 1 KIDS WITH AGE < 10 


KID 
NAME 


SULA 
RISTOPHR 
OTT 

VID 
TRICK 


R> 


ie OF rse clause in the PRINT statement serves the same purpose as a nested 
JR rse statement. The inner RSE (FIRST 1 KIDS WITH AGE < 10) identifies 
ms from the list field KIDS that are included within a FAMILIES record iden- 
ied by the outer FOR rse statement. : 


le equivalent statement using nested FOR rse statements is: 


R FAMILIES FOR FIRST 1 KIDS WITH AGE < 10 PRINT KID_NAME 


r nested repeating fields, use the same technique, but nest FOR statements 

yre than one level. The following example uses the hierarchical domain PETS as 
> record source for the outer FOR loop. The repeating field KIDS is the source 
‘the second FOR loop, and the nested repeating field PET is the source for the 
1ermost FOR loop. The example prints the MOTHER and KID NAME fields to 
ow which PET record and KIDS occurrence the PET occurrence comes from: 


t> FOR PETS WITH ANY KIDS 
\> BEGIN 

> PRINT MOTHER 

\> FOR KIDS WITH ANY PET 


\> BEGIN 

\> PRINT COL 10, KID_NAME 

> FOR PET WITH PET_AGE GT 2 

\> PRINT COL 20, PET_NAME, PET_AGE 
> END 

I> END 


(continued on next page) 
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MOTHER 


LORAINE 
KID 
NAME 
GARY 
PET PET 
NAME AGE 
POP 03 
SODA 04 
SUE 
MOUSE 03 
SHORTY 08 
ANN 
URSULA 
SQUEEKY 03 
FRANK 07 
RALPH 
LOUISE 
ANNE 
FRANK 14 
FRANK 14 
JIM 
ELLEN 
DAVID 
ROBERT 
DTR> 


6.2.3 Retrieving Repeating Field Values with Inner Print Lists 


The simplest way to print a repeating field is to print the entire record containin 
the repeating field: 


DTR> READY FAMILIES 
DTR> PRINT FIRST 1 FAMILIES 


NUMBER KID 


FATHER MOTHER KIDS NAME AGE 
JIM ANN 2  URSULA 7 
RALPH 3 
DTR> 


To print selected fields from the record, you must specify a print list in the 
PRINT statement. (Print lists consist of field names or other value expressions 
and modifiers.) To specify a list item in a print list, you must use an inner print 
list. which has the format: 


ALL print-list OF rse 
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1 the print-list clause of the inner print list, you include the list items you want 
» display. The OF rse clause of the inner print list creates a context for the item 
. the hierarchical list. Example 6-3 prints the name of the mother and informa- 
on about her children for the first FAMILIES record. 


xample 6-3: PRINT Statement with Inner Print List 


CP i ate ES ee en res ee ee ee et 

"R> ! | print-list | 

‘R> ! ane fo mene) ot 7k eee ORE OE 

"R> ! | Inner Print List || 

"R> ! | bs teprceete em alent | | 

‘R> ! | |  |print-list | | | 

"R> ! | || 

"R> PRINT MOTHER, ALL KID_NAME, AGE OF KIDS OF FIRST 1 FAMILIES 

KID 

MOTHER NAME AGE 

IN URSULA “7 !All kids from first family 
RALPH 3 


| this example, ALL KID NAME, AGE OF KIDS is an inner print list. It is also 
1 element of the outer print list that includes the field MOTHER as another ele- 
ent. This outer print list is associated with the target record stream formed by 
ie OF FIRST 1 FAMILIES clause. 


he syntax of the type of PRINT statement that includes an inner print list is: 
RINT print-list, ALL print-list OF rse-1 [,print-list] OF rse-2 


| this syntax. ALL print-list OF rse-1 is the inner print list. The argument rse-1 
eates a record stream from occurrences of a repeating field. That inner record 
ream is itself within the record stream formed by rse-2. 


the inner print list is the first element in the outer print list, you must precede 
e inner print list with another mandatory keyword, ALL. The following example 
similar to the previous one. However, it displays information about children in 
e first FAMILIES record first, then prints the mother’s name: 


R> PRINT ALL ALL KID_NAME, AGE OF KIDS, MOTHER OF FIRST 1 FAMILIES 


KID 
NAME AGE MOTHER 


SULA 7 ANN 
LPH 4 
R> 
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The syntax of this type of PRINT statement that includes an inner print list as 
the first element of the outer print list is: 


PRINT ALL ALL print-list OF rse-1 [,print-list] OF rse-2 


There is only one difference between this syntax diagram and the previous one: 
you need an extra ALL when the first print list element in the outer print list is 
an inner print list. 


There are two important points to remember when working with inner print lists. 


¢ To DATATRIEVE, an inner print list is just another print-list element in thi 
outer print list. 


e An inner print list establishes context for items in a list. 


While inner print lists can complicate statements, they allow you to control com- 
pletely how DATATRIEVE displays repeating fields. By using the repeating field 
as the source for an RSE in an inner print list, you can specify which occurrences 
of the repeating field DATATRIEVE displays. The next example shows the 
results of limiting one or both of the RSEs in a PRINT statement with an inner 
print list: 


DTR> ! Limit the RSE for the inner print list 
DTR> ! to the first occurrence of KIDS from every family: 


DTR> PRINT MOTHER, . !Print list for rse-2 
CON> ALL KID_NAME, AGE - !Print list for rse-1 
CON> OF FIRST 1 KIDS - !'rse-1, uses KIDS as record source 
CON> OF FAMILIES 'rse-2, uses FAMILIES as record source 
KID 
MOTHER NAME AGE 
ANN URSULA 7 !First kid from every family 
LOUISE ANNE 31 
JULIE ANN 29 
ELLEN CHRISTOPHR 0 
ANNE SCOTT 2 
SARAH DAVID (@) 
ANNE PATRICK 4 
MERIDETH BEAU 28 
DIDI 
RUTH ERIC 32 
BETTY MARTHA 30 
LOIS JEFF 23 
SARAH CHARLIE 31 
TRINITA ERIC 16 
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R> ! Limit both RSEs to print the first occurrence 
R> ! of KIDS in the first FAMILIES record: 


R> PRINT MOTHER, !Print list for rse-2 

N> ALL KID_NAME, AGE - !Print list for rse-1i 

N> OF FIRST 1 KIDS - !'rse-1, uses KIDS as record source 

N> OF FIRST 1 FAMILIES 'rse-2, uses FAMILIES as record source 
KID 

MOTHER NAME AGE 

N URSULA 7 'First kid of first family 

R> 


st as with FOR loops, you can nest inner print lists to retrieve desired informa- 


m from nested repeating fields. 


1e following example, like the previous example, retrieves only the information 
»m the first occurrence of the repeating field KIDS from a single record. It uses 
e PETS domain, however. and nests a third print list to display information 


»m the nested repeating field PET: 


R> PRINT MOTHER, 
N> ALL KID_NAME, KID_AGE, 


!Print list for rse-3 
{Print list for rse-2 


N> ALL PET_NAME, PET_AGE - !Print list for rse-1 


N> OF FIRST 1 PET - 
N> OF FIRST 1 KIDS - 
N> OF PETS WITH MOTHER = "ANN" 


KID KID PET 
MOTHER NAME AGE NAME 
N URSULA 7 SQUEEKY 


R> 


'rse-1, uses PET as record source 
!'rse-2, uses KIDS as record source 
!rse-3, uses PETS as record source 


PET 
AGE 


03 'First pet of first kid of 
!family whose mother is Ann 


sing nested inner print lists may require nesting the keyword ALL as well. If 
e inner print list is the first element in the outermost print list, you must pre- 
de it with as many ALL keywords as there are OF RSE phrases in the print 


atement. 
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The following example prints only the names of pets for the first two records in 
the PETS domain and requires three ALL keywords: 


DTR> PRINT ALL - {Print list for rse-3 

CON> LL !Print list for rse-2 

CON> ALL PET_NAME !Print list for rse-1 

CON> OF PET - !rse-1, uses PET as record source 

CON> OF KIDS - !rse-2, uses KIDS as record source 

CON> OF FIRST 2 PETS 'rse-3, uses PETS as record source 
PET 
NAME 

POP 

SODA 

MOUSE 

SHORTY 

SQUEEKY 

FRANK 

DTR> 


6.2.4 Retrieving Repeating Field Values with the Context Searcher 


You can save yourself the difficulty of typing complex inner print lists when deal 
ing with lists and sublists. The VAX DATATRIEVE Context Searcher helps you 
get access to list items. It constructs inner print lists for you once you establish ; 
single record context for it to work on. When you use the name of a list or sublis’ 
item (even sublist items at the sixth level of a hierarchical record). it searches 
through the names of list items, constructing the inner print lists needed to 
retrieve the value. 


You activate the Context Searcher with the SET SEARCH command. When you 
invoke DATATRIEVE, SET NO SEARCH is in effect unless you have a SET 
SEARCH command in your DTR$STARTUFP file. 


The following example shows how the Context Searcher simplifies some of the 
previous examples that used inner print lists: 


DTR> SET SEARCH 

DTR> READY FAMILIES 

DTR> ! Compare with results from 

DTR> ! PRINT MOTHER, ALL KID_NAME OF KIDS, FATHER OF FIRST 1 FAMILIES 
DTR> PRINT MOTHER, KID_NAME, FATHER OF FIRST 1 FAMILIES 

Not enough context. Some field names resolved by Context Searcher. 


KID 
MOTHER NAME FATHER 
ANN URSULA JIM 
RALPH JIM 
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[R> ! Compare with results from 
[R> ! PRINT MOTHER, EACH_KID OF KIDS OF FIRST 1 FAMILIES 


'R> PRINT MOTHER, EACH_KID OF FIRST 1 FAMILIES 
»t enough context. Some field names resolved by Context Searcher. 


KID 
MOTHER NAME AGE : 
iN URSULA 7 
RALPH 3 


[R> ! Compare with results from 

[R> ! PRINT ALL ALL EACH_KID OF KIDS OF 

[R> ! FIRST 1 FAMILIES WITH NUMBER_KIDS = 3 

[R> PRINT EACH_KID OF FIRST 1 FAMILIES WITH NUMBER_KIDS = 3 

»t enough context. Some field names resolved by Context Searcher. 


KID 

NAME AGE 
[FF 23 
‘ED 26 
\URA 21 


[R> ! Compare with results from 
[R> ! PRINT ALL ALL ALL PET_NAME OF PET OF KIDS OF FIRST 2 PETS 


[R> PRINT PET_NAME OF FIRST 2 PETS 
»t enough context. Some field names resolved by Context Searcher. 


PET 
NAME, 


yP 

DA 
JUSE 
1ORTY 
JUEEKY 
LANK 


"R> 


2.5 Retrieving Repeating Field Values by Flattening Hierarchies 


nother way to simplify retrieving values from repeating fields is to “flatten” the 
.erarchical structure of the record. To flatten a hierarchy means to repeat all 
elds in the record for each occurrence of the repeating field. 


lattening the hierarchical domain FAMILIES would mean repeating the 
ATHER. MOTHER. NUMBER KIDS, and the entire list within KIDS fields for 
ich occurrence of the KIDS repeating field. The next two examples compare how 
ie first two records of FAMILIES look when first displayed normally and then 
attened. 
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Normal! display: 


NUMBER KID 


FATHER MOTHER KIDS NAME AGE 
JIM ANN 2 URSULA 7 
RALPH 3 
JIM LOUISE 5 ANNE 31 
JIM 29 
ELLEN 26 
DAVID 24 
ROBERT 16 
Flattened display: 
NUMBER KID KID 
FATHER MOTHER KIDS NAME AGE NAME AGE 
JIM ANN 2  URSULA 7 URSULA 7 
. RALPH 3 
JIM ANN 2 URSULA 7 RALPH 3 
RALPH 3 
JIM LOUISE 5 ANNE 31 ANNE 31 
JIM 29 
ELLEN 26 
DAVID 24 
ROBERT 16 
JIM LOUISE 5 ANNE 31 JIM 29 
JIM 29 
ELLEN 26 
DAVID 24 
ROBERT 16 
JIM LOUISE 5 ANNE 31 ELLEN 26 
JIM 29 
ELLEN 26 
DAVID 24 
ROBERT 16 
JIM LOUISE 5 ANNE 31 DAVID 24 
JIM 29 
ELLEN 26 
DAVID 24 
ROBERT 16 
JIM LOUISE 5 ANNE 31 ROBERT 16 
JIM 29 
ELLEN 26 
DAVID 24 
ROBERT 16 


All the fields repeat. including the entire KIDS list, for each occurrence of the 
repeating fields KIDS. The repetition of the KIDS list in the flattened display 
makes it cumbersome and hard to read. For a more readable display, you can lim: 
the fields to only those you want to see (see the next sections). 
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ou can flatten hierarchies in three different ways to achieve the same results: 


With the CROSS clause 
With inner print lists 
With nested FOR loops 
he next sections discuss these methods. 
2.5.1 Using the CROSS Clause to Flatten Hierarchies -- To create the flat- 


ned display in the previous example, use a PRINT statement with the CROSS 
ause. 


"R> PRINT FAMILIES CROSS KIDS 


NUMBER KID KID 
FATHER MOTHER KIDS NAME AGE NAME AGE 
M ANN 2  URSULA 7 URSULA 7 
RALPH 3 
M ANN 2  URSULA 7 RALPH 3 
RALPH 3 
WIN TRINITA 2 ERIC 16 ERIC 16 
SCOTT 11 
WIN TRINITA 2 ERIC 16 SCOTT 11 
| SCOTT 11 


ATATRIEVE treats KIDS as a domain in this statement. For each “record” in 
e KIDS “domain,” DATATRIEVE prints the corresponding record from the 
4MILIES domain (including the list field KIDS in those records) and the KIDS 
ecord.” 


du-can limit the flattened FAMILIES records displayed by the CROSS clause 
‘using the same techniques you use with two separate domains. DATATRIEVE 
ins the appropriate KIDS “records” with the corresponding FAMILIES record. 


mit the display to joining FAMILIES to first two records of the KIDS 
lomain”: 


R> PRINT FIRST 2 FAMILIES CROSS KIDS :! FIRST 2 in this 
! statement refers to the KIDS 
' "domain," not FAMILIES. 


NUMBER KID KID 
FATHER MOTHER KIDS NAME AGE NAME AGE 
MF: ANN 2 . URSULA 7 URSULA 7 
RALPH 3 
M ANN 2  URSULA 7 RALPH 3 
RALPH 3 
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Limit the display to joining FAMILIES with the KIDS “record” containing 
“URSULA”: 


DTR> PRINT FAMILIES CROSS KIDS WITH KID_NAME CONTAINING "URSULA" 


NUMBER KID KID 
FATHER MOTHER KIDS NAME AGE NAME AGE 
JIM ANN 2  URSULA 7 URSULA 7 
RALPH 3 


DTR> 


The preceding displays included the KIDS repeating field and all the list items it 
contained. To keep from seeing the entire KIDS list for each KIDS “record” dis- 
played, specify only the fields you want displayed in the PRINT statement. 


DTR> PRINT FATHER, MOTHER, NUMBER_KIDS, KID_NAME, AGE OF FAMILIES CROSS 
NUMBER KID 


FATHER MOTHER KIDS NAME AGE 
JIM ANN 2  URSULA 7 
JIM ANN 2 RALPH 3 
EDWIN |, TRINITA 2 ERIC 16 
EDWIN TRINITA 2 SCOTT 11 
DTR> 


You can nest CROSS clauses to retrieve “records” from nested repeating fields. 
The following statement uses the PETS domain, which has the nested repeating 
field PET within the repeating field KIDS. It prints the first 4 “records” in the 
PET “domain” joined with KIDS “domain,” which is itself joined with the PETS 
domain. The statement prints only the elementary fields of the flattened PETS 
record, omitting the list fields. 


DTR> PRINT FATHER, MOTHER, NUMBER_KIDS, - 
CON> KID_NAME, KID_AGE, PET_NAME, PET_AGE 
CON> OF FIRST 4 PETS CROSS KIDS CROSS PET 


NUMBER KID KID PET PET 
FATHER MOTHER KIDS NAME AGE NAME AGE 
JIM LORAINE 2 GARY 24 POP 03 
JIM LORAINE 2 GARY 24 SODA 04 
JIM LORAINE 2 SUE 23 MOUSE 03 
JIM LORAINE 2 SUE 23 SHORTY 08 
DTR> 
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‘you often need to retrieve values in a repeating field of the same domain, you 
an set up a view domain that contains the flattened records. For instance, you 
ould define a view. FLAT FAMILY VIEW, that uses a CROSS clause to flatten 
ire FAMILIES records: 


TR> SHOW FLAT_FAMILY_VIEW 
JMAIN FLAT_FAMILY_VIEW 
OF FAMILIES USING 
1 FLAT_FAMILY OCCURS FOR FAMILIES CROSS KIDS. 
03 FATHER FROM FAMILIES. 
03 MOTHER FROM FAMILIES. 
03 NUMBER_KIDS FROM FAMILIES. 
03 KID_NAME FROM FAMILIES. 
03 AGE FROM FAMILIES. 


[R> 


ou can then use simple PRINT statements to retrieve the repeating field values 
ou need: 


IR> READY FLAT_FAMILY_VIEW 
[R> PRINT FIRST 2 FLAT_FAMILY_VIEW 


NUMBER KID 


FATHER MOTHER KIDS NAME AGE 
IM ANN 2  URSULA 7 
IM ANN 2 RALPH 3 


TR> PRINT FLAT_FAMILY_VIEW WITH AGE GT 30 
NUMBER KID 


FATHER MOTHER KIDS NAME AGE 
IM LOUISE 5 ANNE 31 
EROME RUTH 4 ERIC 32 
AROLD SARAH 3 CHARLIE 31 
AROLD SARAH 3 HAROLD 35 
TR> 


.2.5.2 Using Inner Print Lists to Flatten Hierarchies -- For any PRINT state- 
1ent you use with the CROSS clause, there is an equivalent PRINT statement 
sing inner print lists that produces the same results. The following PRINT 
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statements show the inner print lists that duplicate the results of examples in the 
previous section: 


DTR> ! Duplicate the PRINT FAMILIES CROSS KIDS statement: 
DTR> PRINT ALL ALL FAMILY, EACH_KID OF KIDS OF FAMILIES 


NUMBER KID KID 
FATHER MOTHER KIDS NAME AGE NAME AGE 
JIM ANN 2  URSULA 7 URSULA 7 
RALPH 3 
JIM ANN 2  URSULA 7 RALPH 3 
RALPH 7. 3 
EDWIN TRINITA 2 ERIC 16 ERIC 16 
scOTT 11 
EDWIN TRINITA 2 ERIC 16 SCOTT 11 
SCOTT 11 


DTR> ! Duplicate the PRINT FIRST 2 FAMILIES CROSS KIDS statement: 
DTR> PRINT ALL ALL FAMILY, EACH_KID OF FIRST 2 KIDS OF FIRST 1 FAMILIES 


NUMBER KID KID 
FATHER MOTHER KIDS NAME AGE NAME AGE 

JIM ANN 2  URSULA 7 URSULA ‘i 
RALPH 3 

JIM ANN 2 URSULA . 7 RALPH 3 
RALPH 3 

DTR> ! Duplicate the PRINT FAMILIES CROSS KIDS WITH 

DTR> ! KID_NAME CONTAINING “URSULA" statement: 


DTR> PRINT ALL ALL. FAMILY, EACH_KID - 
CON> OF KIDS WITH KID_NAME CONTAINING "URSULA" OF FAMILIES 


NUMBER KID KID 
FATHER MOTHER KIDS NAME AGE NAME AGE 
JIM ANN 2 URSULA 7 URSULA 7 
RALPH 3 
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‘R> ; pata the PRINT FATHER, MOTHER, NUMBER_KIDS, 
"R> KID_NAME, AGE OF FAMILIES CROSS KIDS statement 
"R> PRINT ALL ALL FATHER, MOTHER, NUMBER_KIDS, KID_ NAME, AGE - 


IN> OF KIDS OF FAMILIES 
NUMBER KID 


FATHER MOTHER KIDS NAME AGE 
M ANN 2  URSULA 7 
M ANN s 2 RALPH 3 
IWIN TRINITA 2 ERIC 16 
IWIN TRINITA 2 ScotTT 1i 


R> ! Duplicate the PRINT FATHER, MOTHER, NUMBER_KIDS, KID NAME, KID_AGE, 


‘R> PET_NAME, PET_AGE OF FIRST 4 PETS CROSS KIDS CROSS PET statement 
'R> PRINT ALL ALL ALL FATHER, MOTHER, NUMBER_KIDS, KID_NAME, KID_AGE, 
IN> PET_NAME, PET_AGE OF FIRST 4 PET OF KIDS OF FIRST 1 PETS 


NUMBER KID KID PET PET 
FATHER MOTHER KIDS NAME AGE NAME AGE 
M LORAINE 2 GARY 24 POP 03 
M LORAINE 2 GARY 24 SODA 04 
M LORAINE 2 SUE 23 MOUSE 03 
M LORAINE 2 SUE 23 SHORTY 08 
'R> 


2.5.3 Using Nested FOR Statements to Flatten Hierarchies -- For any 
RINT statement you use with the CROSS clause, there are equivalent nested 
JOR statements that produce the same results. The following nested FOR state- 
ents duplicate the results of CROSS statements in the previous section: 


R> ! Duplicate the PRINT FAMILIES CROSS KIDS statement: 
‘R> FOR FAMILIES FOR KIDS PRINT FAMILY, EACH_KID 


NUMBER KID KID 
FATHER MOTHER KIDS NAME AGE NAME AGE 
M ANN 2  URSULA 7 URSULA 7 
RALPH 3 
M ANN 2  URSULA 7 RALPH 3 
RALPH 3 
WIN TRINITA 2 ERIC 16 ERIC 16 
SCOTT 11 
WIN TRINITA 2 ERIC 16 SCOTT a1 
SCOTT 11 
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DTR> ! Duplicate the PRINT FIRST 2 FAMILIES CROSS KIDS statement: 
DTR> FOR FIRST 1 FAMILIES FOR FIRST 2 KIDS PRINT FAMILY, EACH_KID 


NUMBER KID KID 
FATHER MOTHER KIDS NAME AGE NAME AGE 
JIM ANN 2 URSULA 7 URSULA rs 
RALPH 3 
JIM ANN 2  URSULA 7 RALPH 3 
RALPH 3 


DTR> ! Duplicate the PRINT FAMILIES CROSS KIDS WITH 

DTR> ! KID_NAME CONTAINING "URSULA" statement: 
DTR> FOR FAMILIES FOR KIDS WITH KID_NAME CONTAINING "URSULA" - 
CON> PRINT FAMILY, EACH_KID 


NUMBER KID KID 
FATHER MOTHER KIDS NAME AGE NAME AGE 
JIM ANN 2‘ URSULA 7 URSULA 7 
RALPH 3 


DTR> ! Duplicate the ee FATHER, MOTHER, NUMBER_ sera KID_NAME, AGE 
DTR> ! F FAMILIES CROSS KIDS statemen 
DTR> FOR FAMILIES FOR. KIDS PRINT FATHER, MOTHER, NUMBER. KIDS, KID_NAME, 


NUMBER KID 


FATHER MOTHER KIDS NAME AGE 
JIM ANN 2  URSULA 7 
JIM ANN 2 RALPH 3 
EDWIN TRINITA 2 ERIC 16 
EDWIN TRINITA 2 SCOTT 11 
DTR> ! Duplicate the 


' 
DTR> ! PRINT FATHER, MOTHER, NUMBER_KIDS, 
DTR> ! KID_NAME, KID_AGE, PET_NAME, PET_AGE - 
DTR> ! OF FIRST 4 PETS CROSS KIDS CROSS PET statement 
DTR> FOR FIRST 1 PETS FOR KIDS FOR FIRST 4 PET - 
CON> PRINT FATHER, MOTHER, NUMBER_KIDS, 


CON> KID_NAME, KID_AGE, PET_NAME, PET_AGE 
NUMBER KID KID PET PET 

FATHER MOTHER KIDS NAME AGE NAME AGE 
JIM LORAINE 2 GARY 24 POP 03 
JIM LORAINE 2 GARY 24 SODA 04 
JIM LORAINE 2 SUE 23 MOUSE 03 
JIM LORAINE 2 SUE 23 SHORTY 08 
DTR> 
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.3 Modifying Values Stored in Repeating Fields 


he techniques used to retrieve data from repeating fields can be adapted for 
iodifying data. This section shows two methods of modifying data stored in 
»peating fields: 


Use FIND and SELECT statements to establish context, and then use the 
MODIFY statement. 


Use FOR statements in combination with the MODIFY statement to estab- 
lish context with nested record streams. 


his section also describes how to change the length of a variable-length list (a 
»peating field defined with the OCCURS DEPENDING clause). For more infor- 
ation about using the MODIFY statement, see Chapter 4 in this manual and 
1e VAX DATATRIEVE Handbook. 


3.1 Modifying Repeating Field Values with FIND and SELECT 


Then you try to change the values stored in repeating fields. you encounter the 
ame complications that occur when retrieving data from repeating fields. 


or instance, you cannot directly modify a field subordinate to a repeating field. 
nce you have selected a record that contains a repeating field. follow these steps: 


Use the FIND statement to create a collection of the occurrences of the 
repeating field. 


Use the SELECT statement to single out one of those occurrences. 


Use the MODIFY statement to change the value of the desired field of the 
occurrence you selected. 


he following example uses this method. It modifies the AGE field in the repeat- 
g field KIDS in the FAMILIES domain. 


"R> ! Create a named collection from FAMILIES domain: 
"R> FIND FIRST 1 FAM IN FAMILIES 


. record found] 
"R> PRINT ALL 


NUMBER KID 


FATHER MOTHER KIDS NAME AGE 
-M ANN 2 URSULA 8 
RALPH 3 


"R> ! Select a record from the named collection: 
"R> SELECT 
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DTR> MODIFY AGE ! Won’t work because AGE is subordinate to KIDS list fi 
"AGE" is undefined or used out of context. 

DTR> ! So, create another collection from the list field KIDS: 

DTR> FIND KIDS 

[2 records found] 

DTR> ! Now select an occurrence of the list field, 

DTR> ! in this case the second: 

DTR> SELECT 2 


DTR> PRINT 

KID 

NAME AGE 
RALPH 3 


DTR> MODIFY AGE ! Now we can modify the AGE field 
Enter AGE: 4 

DTR> ! Check to see that the field was really modified: 
DTR> PRINT 


KID 

NAME AGE 
RALPH 4 
DTR> RELEASE CURRENT 
DTR> PRINT 

NUMBER KID 
FATHER MOTHER KIDS NAME AGE 
JIM ANN 2  URSULA 8 
RALPH 4 

DTR> 


Note that when you modify a selected record. the field you specify following 
MODIFY can never be the OCCURS field itself. In the preceding example, this 
means that you cannot enter MODIFY KIDS. If you want to modify all the fields 
in each occurrence of the repeating field. you can enter the name of a top-level 
group field subordinate to the OCCURS field (not all record definitions contain 
such a field), or you can specify all the elementary fields subordinate to the 
OCCURS field. In the context of the preceding example, this means that you car 
enter MODIFY EACH KID (group field) or MODIFY KID NAME, AGE (list of 
elementary fields) in order to enter a value for each elementary field in the list 
occurrence. 


If you want to change the values of all occurrences of fields subordinate to a 
repeating field. you can add the keyword OF, followed by the name of the repeat- 
ing field. Use this general format: 


MODIFY [ALL] list-item OF list 
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\ATATRIEVE prompts you to enter a value for the field you specify following 
1e MODIFY statement or for each of its elementary items if you specify a group 
eld. 


lote that this format differs from the preceding one by including the OF list 
ause. When you include this clause, you modify all occurrences in the list at 
nee. There are likely to be few times when you want to do that. This format can 
e useful, however. when you want to modify items in a variable length list (one 
ith an OCCURS...DEPENDING ON clause) and one of the following conditions 
true: 


There is more than one occurrence stored in the list and you want all occur- 
rences to contain the same value for the field or fields you modify. 
There is only one occurrence stored in the list. 

he following examples illustrate each of these conditions. 

| record found 


[R> PRINT 
» record selected, printing whole collection. 


[R> FIND eounal = WITH FATHER = "ARNIE" 


NUMBER KID | 


FATHER MOTHER KIDS NAME AGE 
(NIE ANNE 2 SscoTT 2 
BRIAN 0 
"R> ! Oops... Scott and Brian are twenty-year-old twins! 
"R> SELECT 


"R> MODIFY AGE 
iGE" is undefined or used out of context. 


‘R> MODIFY AGE OF KIDS 


iter AGE: 20 
"R> PRINT 
NUMBER KID 
FATHER MOTHER KIDS NAME AGE 
NIE ANNE 2 SCOTT 20 


BRIAN 20 


‘R> FIND FAMILIES WITH FATHER = "JOHN" 
’ records found] 
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DTR> PRINT 
No record selected, printing whole collection. 


NUMBER KID 


FATHER MOTHER KIDS $NAME AGE 

JOHN JULIE 2 ANN 29 
JEAN 26 
JOHN ELLEN 1  CHRISTOPHR O 
DTR> SELECT 2 
DTR> PRINT 
NUMBER KID 

FATHER MOTHER KIDS NAME AGE 

JOHN ELLEN 1  CHRISTOPHR O 


DTR> MODIFY AGE 
"AGE" is undefined or used out of context. 


DTR> MODIFY AGE OF KIDS 
GE: 1 


Enter 
DTR> PRINT 
NUMBER KID 
FATHER MOTHER KIDS NAME AGE 
JOHN ELLEN 1 CHRISTOPHR 1 
DTR> 


6.3.2 Modifying Repeating Field Values with FOR and MODIFY Statements 


You can modify values stored in repeating fields without using collections by nes 
ing record streams with the FOR and MODIFY statements. 


Remember that you can treat the repeating field, or list, as a source of records 
like a domain or collection. Two formats for nesting record streams based on 
repeating fields have different results in modifying values: 


FOR rse MODIFY list-rse USING assignment-statement 


In this format, list-rse is a record selection expression that uses the repeating 
field as the record source. The first RSE specifies the record source and specific 
records to be modified. The list-rse specifies the repeating field and the particula 
occurrences in the list to be modified. 


You supply only one value for each field you specify in the USING clause. If the 


list-rse specifies more than one occurrence in the list. each field value you supply 
applies to them all. 
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‘he following example modifies the name of one child in the FAMILIES domain: 


TR> ! Use SET NO PROMPT to turn off the "(Looking for...]" prompts 
TR> SET NO PROMPT 

TR> ! The outer RSE specifies a single record 

TR> ! from the FAMILIES domain: 

TR> FOR FAMILIES WITH FATHER = "TOM" AND MOTHER = "ANNE" 


JN> ! The inner RSE within the MODIFY statement uses the 
JN> ! repeating field KIDS as a record source and 

IN>. ! specifies a single occurrence of KIDS. Had it 

JN> ! specified more occurrences, they all would be 

JN> ! modified with the value specified in the USING clause: 


JN> MODIFY KIDS WITH KID_NAME = "PATRICIA" USING 


JN> BEGIN 
JN> ! Print the occurrence of KIDS specified: 
JN> PRINT 
JN> ! Change the value of the subordinate field KID_NAME: 
JN> KID_NAME = "PATRICK" 
JN> ! Print the modified occurence of KIDS: 
JN> PRINT 
JN> END 
KID 
NAME AGE 
A\TRICIA 4 
KID 
NAME AGE 
(TRICK 4 
'R> 


‘ith this format, you can modify only a single occurrence of a repeating field or 
ve all occurrences specified in the list-rse the same value. The next format 
10ws how to process independently more than one occurrence in the same 
atement. 


OR rse FOR list-rse MODIFY [field-name [,...] ] 


se this format to independently process more than one occurrence of a repeating 
21d in the same statement. When you use this format, DATATRIEVE prompts 


u to enter field values for as many times as there are occurrences of the repeat- 
g field. 


you do not specify field names, DATATRIEVE prompts you to enter values for 
| fields subordinate to the repeating field. 
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The following example uses this format to change the value of all the occurrences 
of the KIDS repeating field in the first FAMILIES record: 


DTR> FOR FIRST 1 FAMILIES 
CON> 


CON> 
CON> 
CON> 
CON> 
CON> 
CON> 
CON> 
CON> 
CON> 
CON> 
CON> 
CON> BEGIN 

CON> PRINT 


CON> MODIFY AGE 
CON> 


CON> 
CON> 


CON> PRINT 
CON> END 


KID 
NAME AGE 


URSULA 7 
Enter AGE: g 


KID 
NAME AGE 


URSULA 8 
RALPH 3 
Enter AGE: a4 

RALPH 4 


FOR KIDS 


DTR> 


ome cme comm chee 


The RSE in the outer FOR statement 
specifies a single record in 
FAMILIES. If it specified more, 
DATATRIEVE would prompt for 

values for repeating fields in each 
record. 


The inner FOR statement specifies 
all occurrences of KIDS in the 
record or records in the outer 
FOR statement. It could have 
limited the RSE to a single 
occurrence of the repeating field. 


The MODIFY statement specifes that 
only the AGE field subordinate to 
the KIDS repeating field will be 
changed. 


6.3.3 Changing the Length of a Variable-Length List 


If you define a repeating field with the OCCURS DEPENDING clause, you may 
be able to change the number of list items (the number of times a repeating field 
repeats), depending on how you define the data file for the domain: 


¢ The most restrictive case is a data file that you define without the MAX or 
KEY clauses. This creates a sequential file with variable-length records. In 
such a file. you can change only the number of list items up to the value you 
first store in the field referred to in the OCCURS DEPENDING clause. You 
cannot exceed that number because DATATRIEVE determines the length c 
each record when you first store it. 
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For FAMILIES, which uses a sequential file with variable-length records, 
this means you cannot increase the value specified for NUMBER KIDS 
above that entered when the record was first stored: 


DTR> FIND FIRST 1 FAMILIES; SELECT 


DTR> PRINT 
. NUMBER KID 
FATHER MOTHER KIDS NAME AGE 
JIM ANN 2 URSULA 8 


RALPH 4 


DTR> MODIFY NUMBER_KIDS 
Enter NUMBER_KIDS: 3 
Error using RMS file "DTR$LIBRARY:FAMILY.DAT". 
%RMS-F-RSZ, invalid record size 
TR> 


Because you cannot increase NUMBER KIDS, you cannot add information 
on new children to a FAMILIES record. 


If you specify the MAX clause when defining the data file (whether the file is 
indexed or sequential) you create a file with fixed-length records. In a domain 
based on such a file, you can change the number of list items only up to the 
maximum value specified in the OCCURS DEPENDING clause. You cannot 
exceed that value, since the MAX clause in the file definition causes 
DATATRIEVE to create a fixed-length RMS file based on the maximum 
value in the OCCURS DEPENDING clause. 


The least restrictive case is a data file you define using the KEY clause but 
not the MAX clause. This creates an indexed file with variable-length 
records. In such a file, you can change the number of list items to any num- 
ber you want. The following example shows how to increase the number of 
list items for a domain based on an indexed file with variable-length records. 


DTR> READY INDEXED _FAMILIES: WRITE 
DTR> FIND FIRST 1 INDEXED FAMILIES 
[1 Record found] 


DTR> PRINT 
No record selected, printing whole collection 


NUMBER KID 


FATHER MOTHER KIDS NAME AGE 
JIM ANN 2  URSULA T 
RALPH 3 
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DTR> SELECT 

DTR> MODIFY NUMBER_ KIDS 
Enter NUMBER_KIDS: 4 
DTR> FIND KIDS 

[4 records found] 

DTR> SELECT 3 

DTR> MODIFY 

Enter KID_NAME: NICKY 
Enter AGE: 2 

DTR> SELECT 4 

DTR> MODIFY 

Enter KID_NAME: TAM 
Enter AGE: 1 

DTR> PRINT FIRST 1 INDEXED_FAMILIES 


NUMBER KID 


FATHER MOTHER KIDS NAME AGE 
JIM ANN 4  URSULA rs 
RALPH 3 
NICKY 2 
TAM 1 
DTR> 


6.4 Creating Hierarchies with Multiple RSEs 


The complications that occur when you have to retrieve or modify data stored in 
repeating fields make it a good idea to avoid using hierarchical records. 


However, you can have the benefits of hierarchical records without the disadvan- 
tages by creating hierarchies from flat records. There are several advantages to 
hierarchies based on flat records. 


e Because they are based on flat records, you avoid the complications of 
retrieving and modifying data stored in records with repeating fields. You 
can simply print or modify fields directly in domains based on the flat 
records. 


e —_ Like records with repeating fields, they let you display a parent-child rela- 
tionship between data when you want to. 


e They offer more flexibility because the parent-child relationship is not 
imposed by the record definition. 


e There is no limit to the number of occurrences of the “child” record stream 
In records with repeating fields. the OCCURS clause limits how many valu 
a repeating field can store. 
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‘his section describes three techniques for combining record streams to form 
ierarchies: 


View domains 
Inner print lists 
Nested FOR statements 


iach of the techniques creates a hiearchical relationship without using repeating 
elds in a record definition. Instead, they nest record streams from separate 
omains to create the one-to-many relationship characteristic of a hierarchy. 


.4.1. Creating Hierarchies with View Domains 


jew domains do-not form hierarchies unless they nest more than one record 
tream. For instance, view domains that use only fields from a single domain are 
ot hierarchical. 


jews that combine data from two record sources with the CROSS clause are not 
ierarchical either, because the record streams are joined (a one-to-one relation- 
hip between the record streams) instead of nested (a one-to-many relationship 
etween the record streams). The view described in the section on flattening 
ierarchies with the cross clause was an example of this kind of view. 


[owever, any view domain definition that uses more than one OCCURS FOR 
lause creates a hierarchy. It creates a parent-child relationship between the RSE 
pecified in the first OCCURS FOR clause and the RSE specified in the second. | 


‘o access a hierarchical view, you need to use the techniques to retrieve values 
“om repeating fields that are shown in this chapter. (You access a nonhierarchical 
iew as you would any other flat domain. See the chapter on Using View Domains 
yr details.) A hierarchical view domain contains more than one OCCURS FOR 
lause. DATATRIEVE considers the second and following OCCURS FOR clauses 
s lists. or repeating fields. For example. the SAILBOATS domain is a hierachical 
iew based on two domains, YACHTS and OWNERS. 


TR> SHOW SAILBOATS 
OMAIN SAILBOATS 
OF YACHTS, OWNERS BY 
1 SAILBOAT OCCURS FOR YACHTS. 
03 BOAT FROM YACHTS. 
03 SKIPPERS OCCURS FOR OWNERS WITH TYPE EQ BOAT.TYPE. 
O5 NAME FROM OWNERS. 


lote that the second OCCURS FOR clause in SAILBOATS refers to the field 
ame TYPE twice. since the OWNERS and YACHTS domains both have a field 
f that name. You can qualify a field name by adding a prefix to it to differentiate 
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it from the other field with the same name. In this case, BOAT.TYPE specifies 
the TYPE field in the YACHTS domain and distinguishes it from the TYPE field 
in the OWNERS domain. See Appendix A for more information about qualified 
field names. 


After you ready SAILBOATS, the SHOW FIELDS command shows that the sec 
ond OCCURS FOR clause creates a hierarchy: 


DTR> READY SAILBOATS 
DTR> SHOW FIELDS SAILBOATS 


SAILBOATS 
SAILBOAT 
BOAT 
TYPE <Indexed field> 
MANUFACTURER (BUILDER) <Character string, indexed key> 
MODEL <Character string, indexed key> 


SPECIFICATIONS (SPECS) 
RIG <Character string> 
LENGTH_OVER_ALL (LOA - <Character string> 
DISPLACEMENT (DISP) <Number> 
BEAM <Number> 
PRICE <Number> 

SKIPPERS <List> 
NAME <Character string> 


DTR> 


The SKIPPERS field is a list field that repeats for each YACHTS record in the 
outer stream. To refer to field values contained in the list, you must use one of 
the methods in this chapter. For example, use multiple FIND and SELECT state 
ments to print then modify the names of owners of a certain TYPE of yacht: 


DTR> READY SAILBOATS WRITE 

DTR> FIND OWNED IN SAILBOATS WITH ANY SKIPPERS 
[6 records found] 

DTR> PRINT ALL 


LENGTH 
OVER OWNER 
MANUFACTURER MODEL RIG ALL WEIGHT BEAM PRICE NAME 
ALBIN VEGA SLOOP 27 5,070 08 $18,600 STEVE 
HUGH 
C&C CORVETTE SLOOP 31 8,650 09 JIM 
ANN 
ISLANDER BAHAMA SLOOP 24 4,200 08 $6,500 JIM 
ANN 
STEVE 
HARVE 
PEARSON 10M SLOOP 33 12,441 11 TOM 
PEARSON 26 SLOOP 26 5,400 08 DICK 
RHODES SWIFTSURE SLOOP 33 14,000 10 JOHN 


DTR> SELECT 3 
DTR> FIND SKIPPERS 
[4 records found] ~ 
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R> PRINT ALL 


NER 
ME 


M 
N 
EVE 
RVE 


R> SELECT 2 

R> MODIFY NAME 

ter NAME: ANNE 

R> PRINT BOAT, ALL SKIPPERS SORTED BY NAME OF OWNED 


LENGTH 

OVER OWNER 

NUFACTURER MODEL RIG ALL WEIGHT BEAM PRICE NAME 
LBIN VEGA SLOOP 27 5,070 08 $18,600 HUGH 
STEVE 

&C CORVETTE SLOOP 31 8,650 09 eee 

JIM 

SLANDER BAHAMA SLOOP 24 © 4,200 O08 $6,500 ANNE 
. HARVE 

JIM 
STEVE 

EARSON 10M SLOOP 33 12,441 11 TOM 
EARSON 26 SLOOP 26 5,400 08 DICK 
HODES SWIFTSURE SLOOP 33 14,000 10 JOHN 


R> 


ou can use also inner print lists to display the owners of ISLANDER BAHAMA 
ichts directly: 

R> PRINT ALL - 

iN> ALL NAME OF SKIPPERS SORTED BY NAME - 


iN> OF SAILBOATS WITH ANY SKIPPERS AND 
iN> MANUFACTURER = "ISLANDER" 


NER 
ME 


‘NE 
RVE 
M 
EVE 


R> 


4.2 Using Inner Print Lists to Create Dynamic Hierarchies 


1e preceding examples used the view domain SAILBOATS. based on the 
ACHTS and OWNERS domains. To create this view, you needed to use a view 
ymain definition. But you can create the same effect dynamically by using an 
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inner print list. The inner print list can include an RSE that references one 
domain, while the outer RSE refers to a second domain. The following example 
produces the same display as printing the SAILBOATS view domain: 


DTR> PRINT BOAT, 


!Print list for rse-2 


CON> ALL NAME 'Print list for rse-1i 
CON> OF OWNERS WITH TYPE = BOAT.TYPE - !rse-1, uses OWNERS 
CON> OF YACHTS !'rse-2, uses YACHTS 
LENGTH 

. OVER OWNER 
MANUFACTURER MODEL RIG ALL WEIGHT BEAM PRICE NAME 
ALBERG 37 MK II KETCH 37 20,000 12 $36,951 
ALBIN 79 SLOOP 26 4,200 10 $17,900 
ALBIN BALLAD SLOOP 30 7,276 10 $27,500 
ALBIN VEGA SLOOP 27 5,070 08 $18,600 STEVE 

HUGH 

AMERICAN 26 SLOOP 26 4,000 08 $9,895 
AMERICAN 26-MS MS 26 5,500 O8 $18,895 
DTR> 


Here, the inner print list is ALL NAME OF OWNERS WITH TYPE = 
BOAT.TYPE. The inner print list serves to relate each owner of a particular mak: 
and model with that make and model boat in the outer stream, formed from the 
YACHTS domain. 


A second example generates a display of yacht and owner information for any 
yacht that has an owner. This query adds a restriction on the outer RSE using th 
ANY rse Boolean expression: 


DTR> PRINT BOAT, 

CON> ALL NAME 

CON> OF OWNERS WITH TYPE = BOAT.TYPE - 
CON> OF YACHTS WITH ANY 


!'Print list for rse-2 
!Print list for rse-1 
!rse-1, uses OWNERS 
!rse-2, uses YACHTS 


CON> OWNERS WITH TYPE = BOAT. TYPE !rse for ANY clause of rse-2 
LENGTH 
= OVER OWNER 
MANUFACTURER MODEL RIG ALL WEIGHT BEAM PRICE NAME 
_ ALBIN VEGA SLOOP 27 5,070 08 $18,600 STEVE 
HUGH 
C&C CORVETTE SLOOP 31 8,650 09 JIM 
ANN 
ISLANDER BAHAMA SLOOP 24 4,200 08 $6,500 JIM 
ANN 
STEVE 
HARVE 
PEARSON 10M _ SLOOP 33 12,441 11 TOM 
PEARSON 26 SLOOP 26 5,400 08 DICK 
RHODES SWIFTSURE SLOOP 33 14,000 10 JOHN 
DTR> | 
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.4.3 Using Nested FOR Statements to Create Dynamic Hierarchies 


ou can also create dynamic hierarchies by nesting FOR statements. Although 
ested FOR statements are logically equivalent to inner print lists or view 
omains with nested OCCURS clauses, DATATRIEVE displays the data differ- 
atly. 


he following example uses nested FOR statements to retrieve the same informa- 
on that printing the SAILBOATS view domain retrieves: 


fR> FOR YACHTS 

JN> BEGIN 

JN> PRINT BOAT 

JN> FOR OWNERS WITH TYPE = BOAT.TYPE 


JN> PRINT NAME 
JN> END 

LENGTH 

OVER 

ANUFACTURER MODEL RIG ALL WEIGHT BEAM PRICE 
ALBERG 37 MK II KETCH 37 20,000 12 $36,951 
ALBIN 79 SLOOP 26 4,200 10 $17,900 
ALBIN BALLAD SLOOP 30 7,276 10 $27,500 
ALBIN VEGA SLOOP 27 5,070 O08 $18,600 
WNER 
AME 
TEVE 
UGH 
AMERICAN 26 SLOOP 26 4,000 08 $9,895 
AMERICAN 26-MS MS 26 5,500 08 $18,895 
TR> 


’ou can control the printing format to make the display similar to that produced 
y printing the SAILBOATS view domain: 


TR> FOR YACHTS 

ON> BEGIN 

ON> PRINT BOAT 

ON> FOR OWNERS WITH TYPE = BOAT.TYPE 
ON> PRINT COL 60, NAME (-) 

ON> END 
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MANUFACTURER 


ALBERG 

ALBIN 
_ ALBIN 

ALBIN 


AMERICAN 
AMERICAN 


DTR> 


6-42 Using Hierarchies 


MODEL 
37 MK II 
79 
BALLAD 
VEGA 


26 
26-MS 


RIG 


KETCH 
SLOOP 
SLOOP 
SLOOP 


SLOOP 
MS 


LENGTH 
OVER 
ALL 


37 
26 
30 
27 


26 
26 


20 , 000 


WEIGHT BEAM PRICE 


$36,951 
$17 , 900 
$27 ,500 
$18,600 


$9,895 
$18,895 


STEVE 
HUGH 


Part 3 
Programming in DATATRIEVE 
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ften you want to execute the same series of DATATRIEVE commands and 
atements over and over again, and you may want to have other users execute 
1ose Same commands and statements. You have to retype the input each time, 
iless you put the commands and statements in a procedure. By using proce- 
ires, you can develop the series of steps once and then simply invoke the proce- 
ire each time you want to do the same thing again. A procedure is a fixed 
quence of DATATRIEVE commands and statements you create, name, and 
ore in the Common Data Dictionary. 


.1. Defining a Procedure 


or almost any series of commands and statements you use repeatedly, you can 
ive yourself time by defining a procedure. Perhaps there is a simple query you 
ive to enter frequently using a particular database. You might, for instance, 
ish to know all the manufacturers of large yachts: 


'R> READY YACHTS 
'R> FIND BIGGIES IN YACHTS WITH LOA GT 40 SORTED BY BUILDER 


' records found] 
R> PRINT ALL 


LENGTH 
OVER 
NUFACTURER MODEL RIG ALL WEIGHT BEAM PRICE 
HALLENGER 41 KETCH 41 26,700 13 $51,228 
OLUMBIA 41 SLOOP 41 20,700 11 $48,490 
ULFSTAR 41 KETCH 41 22,000 12 $41,350 
SLANDER FREEPORT KETCH 41 22,000 13 $54,970 
AUTOR SWAN 41 SLOOP 41 17,750 12 
EWPORT 41 8 - SLOOP 41 18,000 ii 
LYMPIC ADVENTURE KETCH 42 24,250 13 $80,500 
EARSON 419 KETCH 42 21,000 13 


R> 


f-1 


Although this sequence is short, putting it in a procedure and invoking the proce- 
dure is useful if you need to produce the display frequently. 


To define a procedure, enter the DEFINE PROCEDURE command at 
DATATRIEVE command level: 


DEFINE PROCEDURE procedure-name 


DATATRIEVE then prompts with DFN > to indicate that it expects a procedure 
definition. Enter the commands or statements that form the procedure definition. 
DATATRIEVE continues to prompt with DFN > until you énter the keyword 
END PROCEDURE on a line by itself. 


DTR> DEFINE PROCEDURE BIG_YACHTS 

DFN> READY YACHTS 

DFN> FIND BIGGIES IN YACHTS WITH LOA GT 40 SORTED BY BUILDER 
DFN> PRINT ALL 

DFN> END_PROCEDURE 

DTR> 


As soon as you enter END PROCEDURE. DATATRIEVE stores the procedure 
definition in your default dictionary directory. DATATRIEVE does not check for 
syntax errors when you enter the procedure definition but does check when you 
invoke the procedure. 


7.2 Invoking a Procedure 


You invoke a procedure by preceding its name with the keyword EXECUTE or 
with a colon (:). 


procedure-name 
EXECUTE 


To invoke a procedure, you must have P (PASS THRU), S (SEE), and E 
(EXECUTE EXTEND) access to it. 


The content of a procedure determines where you can invoke it. In general, you 
can invoke a procedure anywhere you can use the commands or statements 
contained in the procedure. For example, if the procedure contains 
DATATRIEVE commands and statements, you can invoke it at the 
DATATRIEVE command level: 


DTR> :BIG_YACHTS 
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7ou cannot invoke a procedure during an ADT, EDIT, or Guide Mode session. 
7ou cannot include a procedure in a domain, record, or table definition. 


JATATRIEVE does not display the contents of procedures as they execute, even 
* you issue the SET VERIFY command. 


"ou do not have to enter DATATRIEVE to invoke a procedure. You can invoke a 
rocedure from the VMS command level. For example. if DTR32 is your DCL 


ymbol for invoking DATATRIEVE, you can invoke BIG YACHTS with this 
ommand line at the system prompt: 


DTR32 EXECUTE BIG_YACHTS 


fter DATATRIEVE executes the last command or statement in the file, you are 
utomatically returned to the system prompt. 


‘ou can use the colon to execute a procedure from VMS level, but you must pre- 
2de it with a semicolon (;): 


DTR32; :BIG_YACHTS 


or DATATRIEVE procedures that are run often from VMS level, you can also 
efine a DCL symbol for the entire command line shown in the last example: 


BIG_YACHTS :== "’’DTR32’; :BIG_YACHTS" 


sers can run DATATRIEVE procedures this way simply by entering at VMS 
»ymmand level the symbol you define. 


.3 Contents of a Procedure 


procedure can contain any number of the following DATATRIEVE elements: 


Full DATATRIEVE commands and statements 
Command and statement clauses and arguments 


Comments 


3.1 Commands and Statements 


hen you execute BIG YACHTS, the results are the same as entering the 
EADY command and the FIND and PRINT statements at command level. 
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DTR> :BIG_YACHTS 


LENGTH 
OVER 
MANUFACTURER MODEL RIG ALL WEIGHT BEAM PRICE 
CHALLENGER 41 KETCH 41 26,700 13 $51,228 
COLUMBIA 41 SLOOP 41 20,700 11 $48,490 
GULFSTAR 41 KETCH 41 22,000 12 $41,350 
ISLANDER FREEPORT KETCH 41 22,000 13 $54,970 
NAUTOR SWAN 41 SLOOP 41 17,750 12 
NEWPORT 41 § SLOOP 41 18,000 11 
OLYMPIC ADVENTURE KETCH 42 24,250 13 $80,500 
PEARSON 419 KETCH 42 21,000 13 
DTR> 


7.3.2 Arguments and Clauses 


Besides full commands and statements, a procedure can contain simply an argu- 
ment or clause from a command or statement. For example, it can contain a 
record selection expression: 


DTR> DEFINE PROCEDURE BIG_YACHTS_RSE 
DFN> BIGGIES IN YACHTS WITH LOA GT 40 SORTED BY BUILDER 
pees END_PROCEDURE 

> 


Having separated the FIND statement from the record selection expression, you 
can invoke the procedure to complete a FIND command: 


DTR> FIND :BIG_YACHTS_RSE 
8 records foun 
DTR> 


In fact. you can use this procedure in any command or statement containing an 
RSE argument, such as the PRINT statement: 


DTR> PRINT ALL :BIG_YACHTS_RSE 


LENGTH 
OVER 
MANUFACTURER MODEL RIG ALL WEIGHT BEAM PRICE 
CHALLENGER 41 KETCH 41 26,700 13 $51,228 
COLUMBIA 41 SLOOP 41 20,700 11 $48,490 
GULF STAR 41 KETCH 41 22,000 12 $41,350 
ISLANDER FREEPORT KETCH 41 22,000 13 $54,970 
NAUTOR SWAN 41 SLOOP 41 17,750 12 
NEWPORT 41 58 SLOOP 41 18,000 11 
OLYMPIC ADVENTURE KETCH 42 24,250 13 $80,500 
PEARSON 419 KETCH 42 21,000 13 
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.3.3 Comments 


Vhen you define a procedure, you can include comments, which DATATRIEVE 
tores in the CDD. 


"you want to display comments on the terminal when you (or another user) 
xecute your procedure, you can use the PRINT command, as shown in the fol- 
wing example: 


ITR> DEFINE PROCEDURE YACHTS_REPORT ; 
*7N> PRINT "THIS REPORT REQUIRES AN ESTABLISHED COLLECTION" 
ie PRINT "SORTED BY BUILDER" 

*N> 

7N> 

*N> 


‘hen you execute the procedure, the first two lines print a message on the 
*rminal: 


[R> : YACHTS_REPORT 


IIS REPORT REQUIRES AN ESTABLISHED COLLECTION 
IRTED BY BUILDER 


nless you use PRINT statements to display comments and messages in a proce- 
ire, DATATRIEVE does not display any of its contents. This is true whether or 
xt SET VERIFY is in effect. You can, however, include comments that are not 


splayed during execution by placing an exclamation point (!) before each com- 
ent line: 


‘R> DEFINE PROCEDURE YACHTS_REPORT 

‘N> ! LATEST VERSION 01-Apr-84 

'N> PRINT "THIS REPORT REQUIRES AN ESTABLISHED COLLECTION" 
'N> PRINT "SORTED BY BUILDER" 


R> :YACHTS_REPORT 


IS REPORT REQUIRES AN ESTABLISHED COLLECTION 
RTED BY BUILDER 


du Can use comments in a procedure to explain the purpose of its parts and. 
nce, make it easy for you and others to maintain. 


4 Editing a Procedure 


hen you invoke a procedure. DATATRIEVE executes each command or state- 
ent in the procedure as if it were entered directly at DATATRIEVE command 
vel. Some errors may occur during execution of the procedure. A typing error, 

r instance, can result in a syntax error in an otherwise correctly formatted com- 
and. If an error occurs during execution, DATATRIEVE prints an error mes- 


ge and terminates the procedure. You can correct the error by using the 
ATATRIEVE Editor. 
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Invoke the Editor with the following command: 
EDIT procedure-name 


When you find the error, use the appropriate Editor commands to correct it. 


7.5 Troubleshooting Procedures 


You can put an entire series of statements into a procedure and then tell 
DATATRIEVE to execute the procedure. If you have made any errors, 
DATATRIEVE stops executing the procedure when it finds the first error and 
sends you an appropriate error message. The following example contains two 
errors: 


DTR> DEFINE PROCEDURE WAGE_REPORT 

DFN> REPORT WAGES 

DFN> SET REPORT_NAME = WEEKLY WAGE REPORT 

DFN> SET COLUMNS-PAGE = 70 

DFN> PRINT LAST_NAME, GROSS_PAY, FICA, 

DFN> FEDERAL_TAX, STATE_TAX, 

DFN> GROSS_PAY - (FICA + FEDERAL_TAX + STATE_TAX)- 
DFN> ("NET PAY") USING $$,$$$.99 

DFN> AT BOTTOM OF REPORT PRINT SKIP 2, COL 1, "TOTAL:", 
DFN> TOTAL GROSS_PAY USING $$$, Dae 99, 

DFN> TOTAL FICA USING $$$ ,$$$.9 

DFN> TOTAL FEDERAL_TAX USING §8° $$$ .99, 

DFN> TOTAL STATE_TAX USING $$$, $$$.99, 

DFN> TOTAL (GROSS_PAY - (FICA + FEDERAL_TAX + 

DFN> STATE_TAX)) USING $$$,$$$.99 

DFN> END_REPORT 

DFN> END_PROCEDURE 

DTR> :WAGE_REPORT 

REPORT WAGES 

SET REPORT_NAME = WEEKLY WAGE REPORT 


Expected header segment, encountered "WEEKLY". 


If you would like to refer to the record definition for the WAGES domain, see th 
record definition appendix in the VAX DATATRIEVE Guide to Writing Reports 


To correct the error in the SET REPORT NAME command, use the Editor and 
place quotation marks (” ”) around WEEKLY WAGE REPORT. Then invoke th 
procedure again: 


DTR> :WAGE_REPORT 
"WAGES" is not a readied source, collection, or list 


DTR> EDIT WAGE_REPORT 


Using the Editor, place the READY WAGES command before the report state- 
ment and invoke the procedure again. 
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R> :WAGE_REPORT 


WEEKLY WAGE REPORT . 9-Aug-1984 
Page 1 

LAST GROSS FEDERAL STATE 

NAME PAY FICA TAX TAX NET PAY 
AKE $1,000.00 $103.86 $204.77 $.01 $691.36 
NN $1,500.00 $145.87 $297 .98 $54.32 $1,001.83 
LL $500 .00 $52.93 $79.75 $32.98 $334.34 
NES $999.99 $103.85 $204.76 $57.90 $633.48 
ONY $1,900.98 $145.87 $375 .98 $75.90 $1,303.23 
ARK $9,500.00 $145.87 $999.84 $106.90 $8,247.39 
TAL: $15,400.97 $698.25 $2,163.08 $328.01 $12,211.63 


6 Aborting Procedures 


yu can abort a procedure by including an ABORT statement in it. If the abort 
nditions arise and SET ABORT is in effect, DATATRIEVE aborts the proce- 
ire and prints a message on your terminal. If SET NO ABORT is in effect, 
ATATRIEVE aborts the statement that contains the ABORT but continues to 
ecute the other commands and statements in the procedure. 


1e default setting in DATATRIEVE is SET ABORT. You can ensure that SET 
3ORT is in effect by including that statement in the procedure definition. For 
ample: . 


R> DEFINE PROCEDURE BIG_YACHTS_QUERY 

N> SET ABORT 

N> DECLARE LENGTH PIC 99 

N> VALID IF LENGTH GT 35. 

N> LENGTH = *."MIN LOA" 

N> IF LENGTH GT 42 

N> THEN ABORT "NO BOATS THAT BIG" 

N> FIND BIGGIES IN YACHTS WITH LOA GE LENGTH 
N> SORTED BY BUILDER 

N> PRINT BUILDER, RIG, LOA, PRICE OF BIGGIES 
N> END_PROCEDURE 


you invoke BIG YACHTS QUERY and supply a length of 35 or smaller, 
ATATRIEVE reprompts you for.a valid length. If you supply a length greater 
an 42, the procedure aborts, prints the specified abort message. and returns you 
the DATATRIEVE command level. 
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DTR> :BIG_YACHTS_QUERY 
Enter MIN LOA: 35 
Validation error for LENGTH 
Re-enter MIN LOA: 43 

ABORT: NO BOATS THAT BIG 
DTR> 


If you assign a value between 36 and 42 to LENGTH, DATATRIEVE prints the 
appropriate collection: 


DTR> :BIG_YACHTS_QUERY 
Enter MIN LOA: 39 


LENGTH 
OVER 
MANUFACTURER RIG ALL PRICE 


BLOCK I. SLOOP 39 

CHALLENGER KETCH 41 $51,228 
COLUMBIA SLOOP 41 $48 , 490 
GULF STAR KETCH 41 $41,350 
ISLANDER KETCH 41 $54,970 


LINDSEY MS 39 $35 ,900 
NAUTOR SLOOP 41 
NEWPORT SLOOP 41 
OLYMPIC KETCH 42 $80 , 500 
PEARSON SLOOP 39 
PEARSON KETCH 42 


7.7 Sample Procedures 


With the information from previous chapters on commands, statements, and pro 
cedures, you have enough techniques available to design numerous procedures. 
Later sections of this chapter describe: 


e Including procedures within other procedures (nesting) 

e Using procedures in compound statements 

e Aborting procedures 

¢ Generalizing procedures so they work on more than one domain 


e Maintaining procedures to accommodate changes you want to make in then 


Use the following examples as models for procedures you create yourself. 
Example 7-1 shows you how to create a procedure that uses the Report Writer t 
write a summary report of yacht data. 
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‘xample 7-1: Sample Procedure Using the Report Writer 


TR> DEFINE PROCEDURE YACHT_SUMMARY 

FN> SET ABORT 

FN> PRINT "THIS REPORT REQUIRES AN ESTABLISHED COLLECTION," 
FN> PRINT "SORTED BY LOA AND BEAM." 


FN> PRINT "HAVE YOU ESTABLISHED A COLLECTION?" _ ---------- (1) 
FN> IF *."YES OR NO" CONTAINING "N" THEN 

FN> ABORT "SORRY, NO COLLECTION." wnnnn-cnnen-----c2--c2n=- (2) 
FN> REPORT ON *."OUTPUT DEVICE OR FILE" = wenennnenn--ne---- (3) 


FN> SET REPORT_NAME="EXAMPLE: REPORT FROM A PROCEDURE" 

FN> SET LINES_PAGE=55, COLUMNS_PAGE=60 

FN> PRINT BUILDER, MODEL, LOA, BEAM, PRICE 

FN> AT BOTTOM OF LOA PRINT SKIP, "AVERAGE PRICE =", AVERAGE PRICE, SKIP 
FN> AT BOTTOM OF REPORT PRINT COL 17,"NUMBER OF BOATS = ", COL 42, COUNT, 
FN> SKIP, "AVERAGE PRICE OF ALL BOATS =", AVERAGE PRICE 

FN> END_REPORT 

FN> END_PROCEDURE 

TR> 


he example illustrates some statements that are particularly useful in 
rocedures: 


L. Use the PRINT statement to display a message to whoever invokes the 
procedure. 


iw 
. 


The prompting value expression *.” YES OR NO” requires the user to 
respond to the question: HAVE YOU ESTABLISHED A COLLECTION? 
The Boolean expression CONTAINING checks the user’s response to the 
question. 


If you invoke YACHT SUMMARY and answer NO to the first prompt, the 
procedure aborts: 


DTR> : YACHT_SUMMARY 

THIS REPORT REQUIRES AN ESTABLISHED COLLECTION, 
SORTED BY LOA AND BEAM. 

HAVE YOU ESTABLISHED A COLLECTION? 

Enter YES OR NO: NO 

ABORT: SORRY, NO COLLECTION. 

DTR> 


If you answer YES to the first prompt. but, in fact, you do not have a cur- 
rent collection, the Report Writer aborts the procedure and prints an error 
message: 


DTR> : YACHT_SUMMARY 
THIS REPORT REQUIRES AN ESTABLISHED COLLECTION, 
‘SORTED BY LOA AND BEAM. 


(continued on next page) 
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HAVE YOU ESTABLISHED A. COLLECTION? 
Enter YES OR NO: YES 


A current collection has not been established. 
DTR> 


The prompting value expression *.” OUTPUT DEVICE OR FILE” allows © 
the user to select the device or file to contain the report when 
DATATRIEVE executes the procedure. 


If you make a collection of YACHTS with LOA between 36 and 37 and pric 
not equal to zero, the following report results: 


DTR> READY YACHTS 

DTR> FIND YACHTS WITH LOA BETWEEN 36 37 AND PRICE NE O 
[5 records found] 

DTR> SORT CURRENT BY LOA, BEAM 

DTR> :YACHT_SUMMARY 

THIS REPORT REQUIRES AN ESTABLISHED COLLECTION, 

SORTED BY LOA AND BEAM. 

HAVE YOU ESTABLISHED A COLLECTION? 

Enter YES OR NO: YES 

Enter OUTPUT DEVICE OR FILE: TT: 


REPORT FROM A PROCEDURE 01-Apr-1984 


Page 1 

LENGTH 

OVER 
MANUFACTURER MODEL ALL BEAM PRICE 
ISLANDER 36 36 11 $31,730 
I. TRADER 37 36 12 $39,500 
AVERAGE PRICE = $35,615 
IRWIN 37 MARK II 37 11 $36,950 
NORTHERN 37 37 11 $50 , 000 
ALBERG 37 MK II 37 12 $36,951 
AVERAGE PRICE = $41,300 


NUMBER OF BOATS = 5 
AVERAGE PRICE OF ALL BOATS = $39 ,026 


How to Nest Procedures Within Procedures 


A nested procedure is a procedure within another procedure. You can use this 
technique to create one procedure that can be used by several other procedures. 
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ne following procedure calculates the price per pound of a boat and assigns a col- 
nn header and edit-string for that value expression. You cannot invoke this pro- 
‘dure by itself, but you can invoke the PRICE PER POUND procedure in 

10ther procedure that prints the builder, model, and price per pound of all boats 
the CURRENT collection. These commands define the two procedures: 


‘R> DEFINE PROCEDURE PRICE_PER_POUND 

'N> PRICE/DISPLACEMENT ("PRICE"/"PER"/"POQUND") USING 
'N> $$9.99 

Ne END_PROCEDURE 

'R> 


R> DEFINE PROCEDURE PRICE_REPORT 

N> PRINT ALL BUILDER, MODEL, :PRICE_PER_POUND 
N> END_PROCEDURE 

R> 


hen you invoke the procedure PRICE REPORT, DATATRIEVE displays the 
ree fields on the terminal. The following example uses the BIG YACHTS pro- 
dure to establish the CURRENT collection and PRICE REPORT to print a 
ort report: 


R> :BIG_YACHTS; :PRICE_REPORT 


LENGTH 
OVER 

NUFACTURER MODEL RIG ALL WEIGHT BEAM PRICE 
HALLENGER 41 KETCH 41 26,700 13 $51,228 
OLUMBIA Ai | SLOOP 41 20,700 11 $48,490 
ULFSTAR 41 KETCH 41 22,000 12 $41,350 
SLANDER FREEPORT KETCH 41 22,000 13 $54,970. 
AUTOR SWAN 41 SLOOP 41 17,750 12 
EWPORT 41 $8 SLOOP 41 18,000 ii 
LYMPIC ADVENTURE KETCH 42 24,250 13 $80,500 
EARSON 419 KETCH 42 21,000 13 

PRICE 

PER 
NUFACTURER MODEL POUND 
HALLENGER 41 $1.92 
OLUMBIA 41 $2.34 
ULFSTAR 41 $1.88 
SLANDER FREEPORT $2.50 
AUTOR SWAN 41 $0.00 
EWPORT 41 Ss 0.00 
LYMPIC ADVENTURE $3.32 
EARSON 419 $0.00 
R> 
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When nesting procedures, do not allow a procedure to invoke itself or you create 
an infinite loop. 


7.9 Using a Procedure in a Compound Statement 


You can invoke a procedure in a REPEAT statement to execute it a number of 
times or in a FOR statement to apply it to a record stream. You must, however, 
use care when invoking a procedure in these statements. For example, the follow- 
ing statement is syntactically correct, but produces results you may not expect: 


REPEAT 5 :procedure-name 


This statement does not execute the procedure five times. When DATATRIEVE 
encounters the first complete statement in the procedure, it assumes that the 
REPEAT statement is also complete. Therefore, it executes the first statement il 
the procedure five times. DATATRIEVE then executes the remaining statement: 
in the procedure once each. 


To repeat the entire procedure, enclose the procedure call or the procedure defini: 
tion in a BEGIN-END block. For example. the following sequence of statements 
puts a procedure call in a BEGIN-END block and repeats the procedure five 
times: 


DTR> REPEAT 5 BEGIN 
Looking for statement] 

CON> :HEAVY_SLOOP 

CON> END 

DTR> 


The following example includes a FOR statement and a BEGIN-END block in a 
procedure definition and invokes the procedure in a REPEAT statement: 


DTR> SHOW HEAVY_SLOOP 
PROCEDURE HEAVY_SLOOP 
FOR YACHTS WITH BUILDER = *. "MANUFACTURER" 
BEGIN 
IF RIG = "SLOOP" AND DISP GE 10000 
PRINT BOAT 
D 


N 
END_PROCEDURE 
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TR> REPEAT 3 :HEAVY_SLOOP 
nter MANUFACTURER: CAL 


LENGTH 
OVER 

ANUFACTURER MODEL RIG ALL WEIGHT BEAM PRICE 
CAL 3-30 SLOOP 30 10,500 10 
CAL 35 SLOOP 35 15,000 11 
nter MANUFACTURER: PEARSON 
PEARSON 10M SLOOP 33 12,441 11 
PEARSON 35 SLOOP 35 13,000 10 
PEARSON 36 SLOOP 37 13,500 11 
PEARSON 39 SLOOP 39 17,000 12 
nter MANUFACTURER: NAUTOR 
NAUTOR SWAN 41 SLOOP 41 17,750 12 
TR> 


f you invoke a procedure in a FOR statement, you must use the same technique: 
nclose the call or the procedure definition in a BEGIN-END block. For instance: 


OR rse BEGIN :procedure-name END 


vemember, if you use a procedure in a loop, do not include any commands or a 
IND, SELECT, DROP, SORT. or REDUCE statement in that procedure. 
\ATATRIEVE does not accept commands or any of these statements in BEGIN- 
‘ND blocks or other compound statements. 


.10 Generalizing Procedures 
ou can generalize procedures so that they operate on numerous domains. Be 
ire that the generalized procedures meet the following two conditions: 
The corresponding fields in the various domains have the same name. 
The procedure refers to an alias rather than to the domain name. 


or example, you might want to keep separate domains for boats from different 
eographical areas, perhaps one each for boats from the east, west, and south 
oasts. If the domains WEST YACHTS, EAST YACHTS, and 

OUTH YACHTS have the same record definition and data file format, you can 
se one procedure on all three. 
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1. When you ready each domain, rename it with an alias, using the AS 
clause in the READY command. To create the alias ALL YACHTS for the 
domain WEST YACHTS, respond to the DTR> prompt with this READY 
command: 


DTR> READY WEST_YACHTS AS ALL_YACHTS 
DTR> 


You have established an alias for the WEST YACHTS domain. During your 
current session, DATATRIEVE recognizes all references to the alias 
ALL YACHTS as references to WEST YACHTS. 


2. When you define a procedure, refer to the alias rather than to a domain 
name. In procedures you have already defined, you can use the EDIT 
procedure-name command to change domain names to an alias. Thus, you 
can generalize the procedure BIG YACHTS QUERY by changing the 
domain name YACHTS in the FIND statement to ALL YACHTS: 


DFN> FIND BIGGIES IN ALL_YACHTS WITH LOA GE LENGTH - 
DFN> SORTED BY BUILDER 


3. When you invoke the BIG YACHTS QUERY procedure, DATATRIEVE 
applies it to the domain readied with the alias ALL YACHTS. After you 
have executed the BIG YACHTS QUERY procedure, you can use it on 
another domain. You must first use the FINISH command to remove the 
readied domain WEST YACHTS under the alias ALL YACHTS from your 
workspace. Then you can ready the next domain you want the procedure 
BIG YACHTS QUERY to work on: 


DTR> READY WEST_YACHTS AS ALL_YACHTS 
DTR> SHOW READY 
Ready sources: 
ALL_YACHTS: Domain, RMS indexed, protected read 
<CDD$TOP . DTR$LIB. DEMO. WEST _YACHTS ; 1> 
No loaded tables. 


DTR> :BIG_YACHTS_QUERY 
Enter min LOA: 39 


LENGTH 
OVER 
MANUFACTURER RIG ALL PRICE 
GOOBER ‘MS 40 $42,000 
HEILE SLOOP 41 $61 , 400 
INVEIGH KETCH 41 $48 ,950 


7-14 Using DATATRIEVE Procedures 


DTR> FINISH 
DTR> SHOW READY 
No ready sources. 
No loaded tables. 
DTR> READY EAST_YACHTS AS ALL_YACHTS 
DTR> SHOW READY 
Ready sources: 
ALL_YACHTS: Domain, RMS indexed, protected read 
<CDD$TOP .DTR$LIB.DEMO.EAST_YACHTS; 1> 
No loaded tables. 


DTR> 


11. Maintaining Procedures 


yu Can maintain the procedures stored in your default dictionary directory with 
e SHOW, EDIT, and DELETE commands. 


11.1. Displaying Procedure Names 


yu can list the names of all procedures in your default directory with the SHOW 
mmand: 


R> SHOW PROCEDURES 


ocedures: 
BIG_YACHTS;1 BIG_YACHTS_QUERY; 1 CHEAP ; 1 
MS_SEARCH; 1 PHONE_REP; 1 TEST; 1 YACHT_SUMMARY; 1 
R> 


11.2 Displaying Procedures 


you want to display a procedure on your terminal, you can use the SHOW com- 
and and specify the name of the procedure to be displayed. You must have P 
ASS THRU), S (SEE), and R (READ) access privilege to the procedure. 


R> SHOW MS_SEARCH 

OCEDURE MS_SEARCH 

ADY YACHTS 

ND YACHTS WITH RIG = "MS" 

R CURRENT PRINT BUILDER, 

JILDER VIA COMPANY_TABLE) ("ADDRESS") 
)_PROCEDURE 


> 
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7.11.3 Deleting Procedures 


You can delete a procedure from your default dictionary directory with the 
DELETE command. You must have P (PASS THRU) and X (EXTEND) access 
privileges to the parent directory and P (PASS THRU) and either D 

(LOCAL DELETE) or G (GLOBAL DELETE) access to the procedure. 


DTR> SHOW PROCEDURES 


Procedures: 
BIG_YACHTS BIG_YACHTS_QUERY CHEAP 
MS_SEARCH PHONE_REP YACHT_SUMMARY 


DTR> DELETE BIG_YACHTS; 
DTR> SHOW PROCEDURES 


Procedures: 
BIG_YACHTS_QUERY CHEAP MS_SEARCH 
PHONE_REP YACHT_SUMMARY 

DTR> 


Note that the DELETE command must end with a semicolon (:). 


To be able to recover your procedure if deleted, you should maintain a backup 
copy (especially if it is a long procedure). Use the DATATRIEVE EXTRACT cor 
mand to copy your procedure to a command file for backup. 


7.12 Protecting Procedures 


When you define a procedure, DATATRIEVE stores the procedure definition in 
your default dictionary directory and creates an access control list for the proce- 
dure. DATATRIEVE automatically stores one access control list entry that speci 
fies your username as the only valid identification and grants you C (CONTROL) 
D (LOCAL DELETE), E (EXTEND/EXECUTE), H (HISTORY), M (MODIFY), 
R (READ). S (SEE), U (UPDATE), and W (WRITE) access privileges. 


You can modify the access control list to give various types of access privilege to 
other users. To execute the procedure, a user must have P (PASS THRU), S 
(SEE), and E (EXTEND/EXECUTE) privileges. 
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‘his chapter discusses two types of command files: 


DATATRIEVE command files that contain only DATATRIEVE commands 
and statements. 


DCL command files that contain a list of DCL commands. A DCL command 
file can also invoke DATATRIEVE and contain DATATRIEVE commands 
and statements. 


‘his chapter describes how to use DATATRIEVE command files and provides 
ome points to keep in mind when using DCL command files with DATATRIEVE 
nd the CDD. 


.1 Using DATATRIEVE Command Files 


\ATATRIEVE command files are similar to procedures. Both contain fixed 
aquences of DATATRIEVE commands and statements, and both allow you to 
xecute frequently used operations. There are, however, some differences between 
ymmand files and procedures: 


You invoke a command file using an at sign (@) before its name, and you 
invoke a procedure using a colon (:).or EXECUTE before its name. 


Command files reside outside DATATRIEVE in a VMS directory, and proce- 
dures are stored in the Common Data Dictionary. Because of this, command 
files have the added security of VMS file protection and access control lists, 
while procedures can take advantage of CDD history and access control 
lists. 
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¢ You can display the commands and statements in a command file as they 
execute by issuing the SET VERIFY command. SET VERIFY does not work 
with procedures. 


e You cannot invoke command files inside a compound statement, such as a 
FOR statement or a BEGIN-END block. You can execute procedures inside 
compound statements. 


Use command files for the following purposes: 


« You can create a DTRSSTARTUP command file (see Chapter 1) that con- 
tains any DATATRIEVE commands and statements you want executed each 
time you use DATATRIEVE. 


¢ You can create and then invoke command files to add definitions of diction- 
ary objects to the Common Data Dictionary. You can change the definitions 
of these dictionary objects by editing them with the DATATRIEVE Editor. 


e You can easily move DATATRIEVE procedures and data definitions around 
the CDD from within DATATRIEVE with command files. Use the 
EXTRACT command to copy a dictionary object to a command file. Use the 
SET DICTIONARY command to move to the desired CDD dictionary and 
invoke the command file. Use the same technique with EXTRACT ALL to 
copy all dictionary objects from one dictionary to another. 


e You can use command files to aid in debugging DATATRIEVE procedures. 
By initially creating procedures as command files and using SET VERIFY, 
you can see statements and commands as they are processed. You can also 
convert existing procedures to command files for the same purpose. See the 
chapter on using procedures and compound statements in the VAX 
DATATRIEVE Handbook for details. 


¢ You can use the EXTRACT command to create command files as backup 
files to maintain the integrity of the CDD. You can use your backup files of 
domain, record, file. and procedure definitions if something happens to cor- 
rupt the CDD and you need to restore the definitions it previously contained 
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8.1.1. Creating a DATATRIEVE Command File 


(ou create a command file with a text editor. You can edit command files with 
ither the DATATRIEVE Editor or any of the various VMS editors. 


‘o create a new command file or edit an esung command file from within 
JATATRIEVE., follow these steps: 


1. Invoke the DATATRIEVE Editor with the EDIT command. 


2. Delete the contents of the editing buffer, which will be the last statement or 
command DATATRIEVE executed. 


3.  Tocreate a new command file, enter the DATATRIEVE commands and 
statements just as you would at the DATATRIEVE prompt. (Do not include 
the prompts DTR>, CON>, DFN>. or RW>.) To edit an existing com- 
mand file, use the INCLUDE file-spec editing command to copy the com- 
mand file into the editing buffer. 


4. To store the new or changed command file, use the WRITE file-spec editing 
command to copy the contents of the buffer to a VMS file. 


wt 


Finally, either exit or quit from the DATATRIEVE Editor. If you use EXIT, 
DATATRIEVE will execute the command file without requiring an explicit 
invocation command. 


o use any of the VMS editors, you must exit from DATATRIEVE and create or 
lit the command file as you would any other file. 


ote that by default DATATRIEVE expects a file type of either .COM or .DTR. 
you use either file type, you do not have to supply it when you invoke the com- 
and file. 


1.1.1. ADT, EDIT, and SET GUIDE in Command Files -- If you put an ADT. 
DIT, or SET GUIDE command in a command file, DATATRIEVE puts you into 
le requested mode and waits for you to respond to the prompt. When you exit 
om the Editor. Guide Mode, or ADT, DATATRIEVE executes the next line in 

.e command file. If that line is a valid response to the prompts of the Editor. 
uide Mode, or ADT. but not a valid DATATRIEVE command or statement. 
ATATRIEVE ignores it. displays an error message on your terminal, and 

turns you to command level. 


1.1.2 Comments in Command Files -- You can include comments in a com- 
and file by placing an exclamation point (!) befere each comment line. If you 
sue the SET VERIFY command, the comments appear on your terminal when 
u invoke the file. along with all the commands and statements in the file. 
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8.1.2. Invoking a Command File 


When you invoke a command file, DATATRIEVE executes each command or 
statement as if you had entered it directly from your keyboard. If you issue a SET 
VERIFY command, or if the command file contains a SET VERIFY command, 
DATATRIEVE displays each command and statement as it executes on your ter- 
minal screen. If an error occurs, DATATRIEVE prints an error message and ter- 
minates the execution of the command file. 


If SET ABORT is in effect. DATATRIEVE returns to command level without 
executing the rest of the procedure or command file. 


If SET NO ABORT is in effect, DATATRIEVE aborts the current statement and 
then processes any statements and commands remaining in the procedure or 
command file. 


8.1.2.1. Invoking a Command File from Within DATATRIEVE -- From within 
DATATRIEVE, you invoke a command file stored in a VMS directory by preced- 
ing the file specification with an at sign (@). To invoke a command file, you must 
enter it on a line by itself, for example: 


DTR> @BIGBOAT.COM 


If the file type is .COM or .DTR and the file is in your default VMS directory, you 
need enter only the file name: 


DTR> @PRT 


If the command file is in another user’s directory, you invoke it by specifying all 
the necessary information in the following format: 


device: [username]filename.type;version 


For example: 


DTR> @DBA2: [WEAVER] BIGBOAT.COM;3 


To invoke a command file in another user’s VMS directory, you must have R 
(READ) access to that directory. . 


You cannot invoke command files while you are in ADT or Guide Mode. 


You can invoke a command file in response to the RW> prompt of the Report 
Writer. The file must begin with valid report statements. After you complete the 
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eport specification in the file with an END REPORT statement, you can follow 
he specification with other valid DATATRIEVE commands or statements. 


.1.2.2. Invoking a Command File Outside of DATATRIEVE -- You need not 
nter DATATRIEVE to invoke a command file. You can invoke a command file 
rom the VMS command level. For example, if DTR32 is your symbol for invok- 
ig DATATRIEVE, invoke PRT.COM in your default VMS directory with this 
ommand line at the system level prompt: 


DTR32 @PRT 


.fter DATATRIEVE executes the last command or statement in the file, you are 
utomatically returned to the system prompt. 


ior DATATRIEVE command files that are‘run often from VMS level. you can 
lso define a DCL symbol for the entire command line. For example. the com- 
1and line in the previous example can be defined as follows: 


PRT :== "?’DTR32’ @PRT" 


'sers can run DATATRIEVE command files at the VMS command level simply 
y entering the symbol you define. 


.1.3 Sample DATATRIEVE Command File 


xample 8-1 shows a command file similar to the YACHT SUMMARY proce- 

are defined in the chapter on using procedures. This example illustrates both the 
milarities and the differences between procedures and command files. The com- 
iand file here is called YSUM.COM. You invoke it with the command file invoca- 
on command (@). 


1 contrast to the sample procedure, if SET VERIFY is in effect, the sample com- 
iand file prints each comment, statement, and command in the file as 
ATATRIEVE encounters it. 


Then DATATRIEVE processes the statement with the *.” YES OR NO” 
‘ompting value expression, it pauses in the execution of the command file to 
ait for the user’s response to the question, "HAVE YOU ESTABLISHED A 
OLLECTION?” As in the sample procedure YACHT SUMMARY, the Boolean 
‘pression CONTAINING checks your response to the question, and, if the 
sponse contains a letter N anywhere. the command file aborts. 


hen DATATRIEVE encounters the *.“OUTPUT DEVICE OR FILE” prompt, 
pauses again for you to select the device or file for output of the report. 


ote that except for the report name, the report produced by the command file is 
e same as the one produced by the procedure YACHT SUMMARY. 
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Example 8-1: Sample Command File Using the Report Writer 


! 

'THIS COMMAND FILE, YSUM.COM, PRODUCES A SUMMARY REPORT OF YACHT DATA 
SET ABORT 

‘THIS REPORT REQUIRES AN ESTABLISHED COLLECTION, 

!'SORTED BY LOA AND BEAM. 

' 


!HAVE YOU ESTABLISHED A COLLECTION? 
IF *."YES OR NO" CONTAINING "N" THEN 
ABORT "SORRY, NO COLLECTION." 

REPORT ON «."OUTPUT DEVICE OR FILE" 

SET REPORT_NAME="SAMPLE REPORT"/"FROM A COMMAND FILE" 

SET LINES_PAGE=55, COLUMNS_PAGE=60 

PRINT BUILDER, MODEL, LOA, BEAM, PRICE 

AT BOTTOM OF LOA PRINT SKIP, "AVERAGE PRICE =", 
AVERAGE (PRICE), SKIP 

AT BOTTOM OF REPORT PRINT COL 13,"NUMBER OF BOATS = ", 
COL 33, COUNT, SKIP, "AVERAGE PRICE OF ALL BOATS =" . 
AVERAGE (PRICE) 

END_REPORT 


When you have readied the domain and established the appropriate collection, 

issue the SET VERIFY command and invoke the command file with an at sign 
(@) and without the .COM file type. DATATRIEVE prints each command and 
statement as it is executed. 


DTR> READY YACHTS 

DTR> FIND FIRST 5 YACHTS WITH LOA BETWEEN 36 37 AND PRICE NE O 
[5 records found 

DTR> SORT BY LOA, BEAM 

DTR> SET VERIFY 

DTR> @YSUM 

SET ABORT 

!THIS REPORT REQUIRES AN ESTABLISHED COLLECTION, 

'SORTED BY LOA AND BEAM. 

" 


‘HAVE YOU ESTABLISHED A COLLECTION? 
IF *."YES OR NO" CONTAINING "N" THEN 
ABORT "SORRY, NO COLLECTION." 

Enter YES OR NO: YES 

REPORT ON «."QUTPUT DEVICE OR FILE" 

SET REPORT_NAME="SAMPLE REPORT"/"FROM A COMMAND FILE" 

SET LINES_PAGE=55, COLUMNS_PAGE=60 

PRINT BUILDER, MODEL, LOA, BEAM, PRICE 

AT BOTTOM OF LOA PRINT SKIP, "AVERAGE PRICE =", 
AVERAGE (PRICE), SKIP 

AT BOTTOM OF REPORT PRINT COL 17,"NUMBER OF BOATS = ", 
COL 40, COUNT, SKIP, “AVERAGE PRICE OF ALL BOATS =",- 
AVERAGE (PRICE) 

END_REPORT 

Enter OUTPUT DEVICE OR FILE: TT: 
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SAMPLE REPORT 1-Aug-1985 


FROM A COMMAND FILE Page 1 
LENGTH 
OVER 
MANUFACTURER MODEL ALL BEAM PRICE 
ISLANDER 36 36 11 $31,730 
I. TRADER 37 36 12 $39 ,500 
AVERAGE PRICE = $35,615 
NORTHERN 37 37 11 $50 , 000 
IRWIN 37 MARK ITI 37 11 $36,950 
ALBERG 37 MK II 37 12 $36,951 
AVERAGE PRICE = $41,300 
NUMBER OF BOATS = 5 
AVERAGE PRICE OF ALL BOATS = $39 , 026 


.1.4 Invoking a Command File from a Procedure 


ou can invoke a command file from a procedure you define with the DEFINE 
ROCEDURE command. 


or example, suppose you create a procedure PICKBOATS to form a collection of 
oats that cost over $10,000. Within the procedure you can invoke the sample 
»mmand file from the previous section, YSUM, to generate the report. Since 
ICKBOATS starts off with the SET VERIFY command, the contents of YSUM 
nut not PICKBOATS) appear automatically on the screen when you execute 
ICKBOATS. 


he procedure PICKBOATS contains some PRINT statements after the 
’YSUM command to illustrate that DATATRIEVE processes all statements in a 
-ocedure before those in a nested command file. 


"R> SHOW PICKBOATS 

{OCEDURE PICKBOATS 

?T VERIFY 

“ADY YACHTS 

-ND YACHTS WITH PRICE GT 10000 SORTED BY LOA, BEAM 
"SUM 

-INT "These lines come AFTER the @YSUM command" 
-INT "in the PICKBOATS procedure." 

-INT "Notice that DATATRIEVE processes them" 
-INT "BEFORE the commands in YSUM." 
ID_PROCEDURE 


(continued on next page) 
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DTR> :PICKBOATS 

These lines come AFTER the @YSUM command 
in the PICKBOATS procedure. 

Notice that DATATRIEVE processes them 
BEFORE the commands in YSUM. 


SET ABORT 

'THIS REPORT REQUIRES AN ESTABLISHED COLLECTION, 
!'SORTED BY LOA AND BEAM. 

! 


'HAVE YOU ESTABLISHED A COLLECTION? 

IF *."YES OR NO" CONTAINING "N" THEN ABORT "SORRY, NO COLLECTION." 
Enter YES OR NO: Y 

REPORT ON *«."OUTPUT DEVICE OR FILE" 

SET REPORT-NAME="SAMPLE REPORT"/"FROM A COMMAND FILE" 

SET LINES-PAGE=55, COLUMNS-PAGE=60 

PRINT BUILDER, MODEL, LOA, BEAM, PRICE 

AT BOTTOM OF LOA PRINT SKIP, "AVERAGE PRICE =", 

AVERAGE PRICE, SKIP 

AT BOTTOM OF REPORT PRINT COL 17, “NUMBER OF BOATS = ", 

COL 40, COUNT, SKIP, "AVERAGE PRICE OF ALL BOATS =", AVERAGE PRICE 
END_REPORT 

Enter OUTPUT DEVICE OR FILE: TT: 


SAMPLE REPORT 1-Aug-1985 
FROM A COMMAND FILE Page 1 
LENGTH 
OVER 
MANUFACTURER MODEL ALL BEAM PRICE 
EASTWARD HO 24 09 $15,900 
AVERAGE PRICE = $15,900 
IRWIN 25 25 12 $10,950 
AVERAGE PRICE = $10,950 
GRAMPTAN 26 26 08 $11,495 
AMERICAN 26-MS 26 08 $18,895 
WESTERLY CENTAUR 26 08 $15,245 
TANZER 26 26 09 $11,750 


ALBIN 79 26 10 $17,900 


DTR> 
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t is important to remember that a command file within a procedure is always 
‘xecuted after all the other statements in the procedure. 


s.1.5 | invoking a Command File from Another Command File 


(ou can invoke procedures and command files from within a command file. For 
mxample, the command file MSMOD readies the YACHTS domain then executes 
he command file MOD. MOD contains a loop with a FOR statement and a 
3EGIN-END block of statements that allow the user to modify prices 
nteractively: | 


TR> SET VERIFY 
TR> @MSMOD 
MSMOD contains only the next two lines: 
EADY YACHTS WRITE 
MOD 


MOD contains the following lines: 


OR YACHTS WITH RIG = "MS" 
BEGIN 
PRINT 
IF. *."Y TO MODIFY, N TO SKIP" CONTAINING "y" 
THEN MODIFY PRICE ELSE 
PRINT "NO CHANGE" 
IF *."Y TO CONTINUE, N TO ABORT" CONTAINING "N" 
ABORT "END OF PRICE CHANGES" 


END 
LENGTH 
OVER 
ANUFACTURER MODEL RIG ALL WEIGHT BEAM PRICE 
AMERICAN 26-MS MS 26 5,500 08 $18,950 


nter Y TO MODIFY, N TO SKIP: Y 
nter PRICE: 19350 
nter Y TO CONTINUE, N TO ABORT: Y 


ZASTWARD HO MS 24 7,000 09 $15,900 
ater Y TO MODIFY, N TO SKIP: N 
) CHANGE 


ater Y TO CONTINUE, N TO ABORT: N 
30RT: END OF PRICE CHANGES 

[TR> FIND YACHTS WITH RIG = "MS" 

> records found] 


[R> SELECT 
[R> PRINT 
LENGTH 
OVER 
\NUFACTURER MODEL RIG ALL | WEIGHT BEAM PRICE 
\MERICAN 26-MS MS 26 5,500 08 $19,350 
[R> 
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Recall that you cannot use commands in compound statements. Because the at 
sign (@) is a command (the Invoke Command File command), you cannot use the 
at sign within a compound statement. In other words, you cannot invoke com- 
mand files from within compound statements. 


When embedding command files within other command files (also called nesting), 
do not allow a command file to invoke itself, either directly or indirectly, come ® sO 
may create an infinite loop. 


8.1.6 Aborting Command Files 


To abort a command file that contains an error, include an ABORT statement in 
the file. If the responses meet the abort conditions and SET ABORT is in effect, 
DATATRIEVE aborts the command file and prints the message specified for the 
ABORT statement. If SET NO ABORT is in effect, DATATRIEVE aborts the 
command or statement that contains the ABORT but continues to execute the 
remaining commands and statements in the file. 


8.1.7 Maintaining Command Files 


VMS directories, not the CDD, store the command files. If you adopt the conven: 
tion of using .COM as the file type for command files, you can display the names 
of your command files on your terminal by requesting a directory listing of 

* COM at the DCL command level. You can adopt any other convention you wis} 
and use the wildcard in the same manner. 


$ DIRECTORY *.COM 


YSUM.COM;1 WIDTH.COM;1 SAMPLE .COM;1 


‘You can display the contents of a command file with the DCL TYPE command: 


$ TYPE SAMPLE.COM 


You can delete a command file from your directory with the DCL DELETE 
command: 


$ DELETE SAMPLE. COM; * 


8.1.8 Protecting Command Files 


Command files have more protection from unauthorized use than DATATRIEVI 
procedures do. Each procedure does have its own access control list that 
DATATRIEVE checks when someone invokes the procedure, but whoever has 
access to the CDD has read and write access to procedures. Command files, on 
the other hand, have VMS protection. To prevent people from using your com- 
mand files, you can change the VMS protection to deny R (READ) access to 
others. 
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2 Using DCL Command Files 


ATATRIEVE lets you execute commands, statements, procedures, and com- 
and files from DCL command level. You can do this by defining a symbol to 
voke DATATRIEVE and following the symbol with any legal DATATRIEVE 
mmand. (See Chapter 1 for details.) 


yu can embed such a DCL command line in a DCL command file. When you do 
is, you have to keep in mind some special precautions. This section describes 
ose precautions. 


2.1 Reassigning SYSSINPUT in Command Files That Require Interactive 
Input 


‘ default, DCL command procedures expect any data or other input to come 
om the command procedure itself. The DCL command file will not work if it 
vokes DATATRIEVE and DATATRIEVE requires input from the terminal. 
‘cause of this. vou must reassign the logical name SYS$INPUT. 
\TATRIEVE requires input from the terminal when it: 


Executes any command, statement, procedure, or command file that 
prompts the user for input 


Uses a forms product 
reassign the logical name SYS$INPUT so the DCL command procedure 


pects input from the terminal, precede the command that invokes 
\TATRIEVE with this ASSIGN command: 


SIGN/USER_MODE SYS$COMMAND SYS$INPUT 


the symbol to invoke DATATRIEVE is DTR382, and the procedure 
tOMPTER requires terminal input, that means the DCL command file must 
atain the following lines: 


ASSIGN/USER_MODE SYS$COMMAND SYS$INPUT 
JTR32 EXECUTE PROMPTER 


2.2 Command Files with an Invalid COD$DEFAULT Can Damage the CDD 


a DCL command file uses an equivalence to the logical name COD$DEFAULT 
at is not a valid CDD path name, subsequent commands in the file could delete 
otherwise damage CDD directories. | 
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There are several ways to assign an invalid CDD$DEFAULT: 


© You might misspell the name of a dictionary directory in assigning 
CDD$DEFAULT: for example, you might type CDD$TOP.SOLES instead 
of CDD$TOP.SALES. 


¢ You might delete the directory you specified as the CDD$DEFAULT and 
forget to specify another CDD$DEFAULT. 


e You might assign a logical name to CDD$DEFAULT. CDD$DEFAULT is 
already a logical name. The CDD translates only one logical name, so it 
assumes that the logical name you assigned to COD$DEFAULT is a full or 
relative path name, not another logical name. 


When the DMU utility cannot use the CDD$DEFAULT you have defined, it sets 
your default dictionary directory to CDD$TOP, the only node certain to exist in 
every CDD. This action can cause a problem if it occurs during execution of a 
command file. For example. consider what might happen when the following com 
mand file executes: 


$ ON WARNING THEN EXIT 
$ RUN SYS$SYSTEM : DMU 
DELETE/ALL 

EXIT 


Before DMU can execute the DELETE/ALL command, it must find the default 
directory. If it finds an invalid default directory, it issues DMU and CDD error 
messages and sets the default directory to CDD$TOP. The DCL command ON 
WARNING THEN EXIT does not stop execution of the command file because 
DMU continues to execute in spite of the error. Instead of deleting every direc- 
tory and object under the default directory, DMU deletes everything under 
CDD$TOP. Similar, but less drastic results can occur in any command file that 
has an invalid CDD$DEFAULT and attempts to alter the dictionary in any way. 


If a command file invokes DATATRIEVE and CDOD$DEFAULT is incorrectly 
defined. no DATATRIEVE commands can execute. You cannot run 
DATATRIEVE when CDD$DEFAULT is incorrectly defined. However, you can 
run DATATRIEVE if CDD$DEFAULT is not defined at all or if you type 
DEASSIGN CDD$DEFAULT. In this case. DATATRIEVE sets your default dic 
tionary directory to CDD$TOP and you run the risk of unintentionally altering 
CDD$TOP. 


There are several safeguards you can implement to help protect the CDD agains! 
this type of error: 


e Check the translation of CDD$DEFAULT before executing a command file 
that alters the dictionary. 
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Limit everyone except the system manager or data administrator to 

PASS THRU privilege at CDD$TOP. Then, if users unintentionally set their 
default directories to CDD$TOP, they are unlikely to have sufficient privi- 
leges to alter the dictionary. 


Always define CDD$DEFAULT as a path name, not a logical name. 


Use full path names rather than relative path names in command files that 
alter the dictionary. 


Avoid the use of powerful commands, such as DELETE/ALL, in command 
files. 
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variable is a symbol whose value can change as you execute a program. You can 
se the letter A as a variable. for instance. The name of the variable stays the 
ime, but its value can change as DATATRIEVE acts upon it. You use variables 
DATATRIEVE: 


To assign values to fields in STORE and MODIFY statements 
As counters in FOR, REPEAT, and WHILE loops 
As conditional values in Boolean expressions 


To specify field names that would otherwise be ambiguous 


1 Declaring Variables 


yu declare a variable with a statement in this form: 
=<CLARE variable-name variable-definition. 


ie variable name is the name you give to the variable. The variable definition _ 
nsists of field definition clauses. When you declare a variable, you can use any 
the DATATRIEVE definition clauses except OCCURS and REDEFINES. You 
ist include at least one PIC, COMPUTED BY or USAGE clause. You can also 
e the QUERY-HEADER, EDIT-STRING, SIGN, MISSING VALUE, and 
SFAULT VALUE clauses. 


declare the variable A to be a three-digit numeric value with an initial value of 
0, you use this variable name and variable definition: 


t> DECLARE A PIC 999. 
i> A= 0 


If you print the variable, it looks like this: 
DTR> PRINT A 
A 


000 


You can define two kinds of variables: 


e Local variables 
e Global variables 


You use the DECLARE statement to define both local and global-variables. A 
variable you define within a BEGIN-END statement is a local variable, and you 
can use it only within that statement. A variable you define at DATATRIEVE 
command level is a global variable. It remains in your workspace until you release 
it or exit from DATATRIEVE. Use the assignment statement (variable = value) 
to set the variable to a particular value. For example: 


DTR> DECLARE BIG PIC X(5). 
DTR> BIG = "YES " 
DTR> PRINT BIG 
BIG 
YES 
The initial value for variables in numeric fields is 0. In alphanumeric strings. it is 


spaces. These are the default values if you do not specify a different default value 
or missing value. 


You can also use a date field as a variable, as in this example: 


DTR> DECLARE Y USAGE DATE EDIT_STRING DD-MMM-YY. 
DTR> Y = "TODAY" 
DTR> PRINT Y 


Y 


19-May-84 
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.2- Local Variables 


‘ou define local variables with DECLARE statements entered in BEGIN-END 
nd THEN statements. The local variable has an effect only within the clause or 
tatement in which you declare it. 


1 the following example, the local variable declared in the inner statement super- 
2des one with the same name declared in the outer statement. Notice that the 
ifferent value or different data type assigned to the inner variable has no effect 

1 the value of the variable in the outer statement. Note also that neither local 
ariable exists when DATATRIEVE finishes executing the compound statements 
yntaining them both: 


[R> SET NO PROMPT 

(R> BEGIN 

\N> DECLARE X PIC XXX. 
)N> X = "TOP" 

\N> PRINT X 


IN> BEGIN 

)N> DECLARE X PIC 9.99. 
\N> X = 1.23 
\N> PRINT X 
IN> END 

IN> PRINT X 

IN> END 

Ip 

23 

P 

R> 


3 Global Variables 


ippose you want to assign to each boat in YACHTS a new price that is two- 
irds of the present price. Using a COMPUTED BY clause in a global variable. 
u can apply a single formula to every yacht, as in the next example. Use the 
ECLARE statement to create the variable. Use a COMPUTED BY clause with 
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a value expression to calculate the changed values: 


DTR> READY YACHTS MODIFY 

DTR> DECLARE FIRE_PRICE COMPUTED BY PRICE/1.5 
CON> EDIT_STRING IS $99,999.99. 

DTR> FIRE_PRICE = 0 

DTR> FOR FIRST 5 YACHTS PRINT BOAT, FIRE_PRICE 


LENGTH 
OVER FIRE 
MANUFACTURER MODEL RIG ALL WEIGHT BEAM PRICE PRICE 
ALBERG 37 MK II KETCH 37 20,000 12 $36,951 $24,634.00 
ALBIN 79 SLOOP 26 4,200 10 $17,900 $11,933.33 
ALBIN BALLAD SLOOP 30 7,276 10 $27,500 $18,333.33 
ALBIN VEGA SLOOP 27 5,070 08 $18,600 $12,400.00 
AMERICAN 26 SLOOP 26 4,000 08 $9,895 $06,596.67 


DTR> 


The variable FIRE PRICE declared at DATATRIEVE command level remains in 
the workspace throughout the session. It changes its value whenever the value of 
PRICE changes. (See Appendix A for a discussion of context changes.) The vari- 
able remains in your workspace until you release the variable with a RELEASE 
statement or declare another global variable with the same name. 


9.4 Using Variables to Assign Values to Fields 


You can use variables to assign values to fields in the USING clauses of STORE 
and MODIFY statements. You cannot, however, use a variable to respond to a 
prompt for a field value, whether the prompt is the result of the STORE or 
MODIFY statement or of a prompting value expression in an assignment 
statement. 


In the USING clause of the STORE and MODIFY statements, you can supply 
values for fields by using value expressions on the right side of assignment state- 
- ments. In some circumstances, you can use variables in those assignments to con- 
trol the uniformity of input data. 


In this example. WORK is a domain you want to contain uniform names. The 
domain is indexed on WHO and allows duplicates: 


DTR> SHOW WORK_REC 
RECORD WORK_REC 
USING 
01 TOP. 
03 JOB PIC X(15). 
03 RESPONSIBLE_PERSON PIC X(4) 
QUERY_NAME WHO. 
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VAME TABLE translates the varying inputs into uniform values to store in the 
vork domain: 


‘TR> SHOW NAME_TABLE 
‘ABLE NAME TABLE 
DIT_STRING IS X(16) 


D : ED 
M : ED 


H : 
RED : FRED 


BL : RICK 
ICK RICK 


L : 
LSE "NOT A VALID NAME" 
ND_TABLE 


n the following STORE statement, the USING clause uses the variable 
'ERSON with a prompting value expression for the responsible person. The table 


ranslates the value supplied to that prompt and stores the uniform results in the 
eld WHO: 


TR> SET NO PROMPT 

TR> DECLARE PERSON PIC X(16). 
ITR> READY WORK WRITE 

IR> REPEAT 3 STORE WORK USING 
JN> BEGIN 

JN> JOB = «.JOB 

JN> PERSON = *.WHO . 

JN> WHO = PERSON VIA NAME_TABLE 
JN> END 

iter JOB: CLEANING 

iter WHO: © . 

iter JOB: DRYING 

iter WHO: FR 

iter JOB: SELLING 

iter WHO: R 

[R> PRINT WORK 


RESPONSIBLE 
JOB PERSON 


sEANING ED 


tYING NOT A VALID NAME 
ILLING RICK 


*R> 
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9.5 Changing the Value of a Variable 


You can change the value of a variable with an assignment statement, using any 
DATATRIEVE value expression on the right side of the statement. You can also 
use a prompting value expression to change the value of a variable. This example 
declares a variable and changes that value first with an assignment statement 
and then with a prompting value expression: 


DTR> DECLARE X PIC XXX. 
DTR> X = 0 
DTR> PRINT X 


X 

0 

DTR> X = "ABC"; PRINT X 
X 

ABC 


DTR> X = *."VALUE FOR X" 
Enter VALUE FOR X: LIP 
DTR> PRINT X 

X 


LIP 


DTR> 


9.6 Using Context Variables 


DATATRIEVE provides a different kind of variable from the ones previously dis 
cussed in this chapter. This is called a context variable. Instead of storing values 
context variables serve as labels that identify a record stream to DATATRIEVE 
You assign context variables to be temporary names of particular record stream: 
In this way you can make clear the domain from which a record stream originate 
or you can create two different record streams based on the same domain. 


In most cases. DATATRIEVE will know to what record stream a field name 
applies without needing context variables. For example, DATATRIEVE does no 
need context variables in the following store statement: 


DTR> ! First, define a domain that will hold a subset 
DTR> ! of YACHTS records, namely, those that 

DTR> ! cost more than $20,000. 

DTR> DEFINE DOMAIN RITZY_ONES USING YACHT ON RITZY; 
DTR> DEFINE FILE FOR RITZY_ONES 

DTR> READY RITZY_ONES WRITE 


9-6 Using DATATRIEVE Variables 


ITR> ! The FOR statement includes a STORE USING statement 
ITR> ! to store the desired records in RITZY_ONES. 

ITR> ! Note that you don’t need context variables. 

ITR> FOR YACHTS WITH PRICE > "$20,000" 

‘ON> STORE RITZY_ONES USING 


‘ON> BEGIN 

‘ON> TYPE = TYPE 
‘ON> PRICE = PRICE 
‘ON> END 


n this example. DATATRIEVE assigns the values of TYPE and PRICE of all 
mats in YACHTS that cost more than $20,000 records in to a new domain called 
tITZY ONES. 


should you so choose, however, you can use context variables to identify record 
treams and to qualify field names. This makes your statements and procedures 
2ss ambiguous and easier to maintain. For example, you can perform the preced- 
ag store operation as follows: 


TR> FOR Y IN YACHTS WITH PRICE > "$20,000" 
ON> STORE R IN RITZY_ONES USING 


ON> BEGIN 

ON> R.TYPE = Y.TYPE 
ON> R.PRICE = Y.PRICE 
ON> END 


1 certain cases, however, you must use context variables to identify a record 
tream explicitly. When you need to access the same domain two or more times in 
ne statement, or when you need to compare record streams from the same 
omain. you must use context variables. In all other cases, you can use the 

omain name for qualifying field names, or else DATATRIEVE resolves the con- 
»xt automatically (as in the first example above). 


ut when you must establish two record streams from the same domain. or when 
du cross a domain over itself. you use context variables to label different record 
‘reams. By qualifying each field name with the context variable and a period (.), 
du indicate clearly to DATATRIEVE how to evaluate field references. In the 
dove example, DATATRIEVE looks to the R stream to evaluate R.TYPE and to 
1e Y stream to evaluate Y. TYPE. Thus DATATRIEVE allows you to create two 
r more) record streams from the same domain without confusing or mixing 
‘cords. 


or example, assume that you are interested in finding the average payroll of 

ich department in the PERSONNEL domain. You need to access all the records 
PERSONNEL twice, once to group them by department and again to compute 
ie average Salary. . 
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Using context variables allows you to distinguish the references to PERSONNEL 
so that you can perform both operations within the same statement: 


DTR> FOR D IN PERSONNEL REDUCED TO DEPT 
CON> PRINT D.DEPT, AVERAGE SALARY OF S IN PERSONNEL WITH - 
CON> S.DEPT = D.DEPT 


AVERAGE 
DEPT SALARY 


C82 $40,493 
D98 $42,244 
E46 §=$39,658 
Fi1 $37,892 
G20 $39,185 
T32 $39,144 
TOP $75,892 


DATATRIEVE reduces the PERSONNEL domain to unique occurrences of the 
DEPT field. This record stream is identified by the context variable D. Then, for 
each value of DEPT in the D stream, DATATRIEVE calculates the average sal- 
ary of all records in the S stream that have matching values for DEPT. 


For another example, assume that you wish to find how much of the company’s 
workforce each department employs. You can perform the query in the following 
manner: 


DTR> FOR D IN PERSONNEL REDUCED TO DEPT 
CON> PRINT D.DEPT, 100 « ((COUNT OF PER IN PERSONNEL - 
CON> WITH PER.DEPT = D.DEPT)/ COUNT OF PERSONNEL) ("PCT") USING z9.9% 


DEPT PCT 


C82 21.7% 
p9s8.—s«17.4% 
E46 8.7% 
Fit 17.4% 
G20 13.0% 
T32 17.4% 
TOP 4.3% 


This statement sets up an inner loop of records from the PERSONNEL domain 
identified by the context variable PER and an outer loop of records from the san 
domain identified by the label D. For each group of records with the same depar 
ment, DATATRIEVE counts the records and divides it by the total number of al 
records in PERSONNEL. The context variables D and PER allow vou to refer ti 
the same records in the PERSONNEL domain twice. Thus you can print out all 
the department names and count all their members in the same statement. 
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ection 2.4 contains an example illustrating the use of context variables to com- 

ire record streams from the same domain. Appendix A contains more examples 
‘context variables and presents detailed information about how DATATRIEVE 
‘solves context. 
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Part 4 
Optimizing DATATRIEVE 
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ris chapter describes how to create new domains with data from existing ones. 
ou might do this to: 
Add new fields to the record definition associated with the domain 
Change field definitions to affect the values stored in the data file 
Rearrange the fields in the record definition 
Combine data from two or more domains - 
Create a copy of a domain for testing 
Change the file organization 
-- Change the index structure (key fields) 


Create a domain that contains a subset of records contained in another 
domain . 


yw you create the new domain depends on whether you want to keep the old 
main. If you want to keep the old domain, follow these three steps when creat- 
x the new domain: 


Define the new domain, its record, and its data file. 


Ready the new domain for WRITE access and the old domain for READ 
access. 


Use the DATATRIEVE Restructure statement to transfer field values from 
the old data file to the new one. 


7ou want to use any old procedures on the new domain, you must edit them 
hey refer to fields not included in the new domain. Follow your standard 
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DATATRIEVE editing procedure to make the necessary changes, using: 
EDIT procedure-name 


If the old procedures refer only to fields included in the new domain, you need not 
change the procedures. You can ready the new domain with the old domain name 
as an alias (READY NEW AS OLD) and execute the old procedures. 


If you do not want to keep the old domain, you can still use the old procedures if 
you follow these steps: 


1. Define the new domain (NEW), record (NEW REC), and file (NEW.DAT). 


2. Use the Restructure command to transfer the data from the old domain 
(OLD) to the new one (NEW). 


3. Delete the definition of the old domain (OLD). 


4. Enter another domain definition that uses the old domain name (OLD), the 
new record definition (NEW REC), and the new data file (NEW.DAT): 


DTR> DEFINE DOMAIN OLD USING NEW_REC ON NEW.DAT; 
DTR> 


5. Check the old procedures for any references to field names not included in 
the new record definition, and edit where necessary. 


Note 


You cannot use DATATRIEVE to restructure DBMS or Rdb domains. 
You must use RDO to restructure Rdb domains. You must use the 
VAX DBMS DDL compilers and DBO utility to restructure databases. 
However, you can store data from DBMS or Rdb domains in RMS 
domains. 


10.1 A Sample Domain 


PROJECTS is a sample domain you can create to practice restructuring: 


DTR> SHOW PROJECTS, PROJECT_REC 

DOMAIN PROJECTS USING PROJECT_REC ON PROJECT; 

RECORD PROJECT_REC 

O1 PROJECT_REC. 
03 PROJ_CODE PIC 9(3) QUERY_NAME IS CODE. 
03 PROJ_NAME PIC X(10) QUERY_NAME IS NAME. 
03 MANAGER_NUM PIC 9(5) QUERY_NAME IS NUM. 
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he data file PROJECT.DAT is a sequential file and contains these records: 
[R> PRINT PROJECTS 


tOJ PROJ _MANAGER 


)DE NAME NUM 
)2 GROUNDS 00006 
45 BUILDING 2 00003 
18 SHED 00002 
.8 RESEARCH 00006 
37 PUB REL 00008 


'3. MATERIALS 00002 
"R> 


0.2 Adding Fields to a Record Definition 


9 create a new domain with two fields added to PROJECT REC, you follow 
iese steps: 


Define a new domain: 


DTR> DEFINE DOMAIN NEW_PROJECTS 
DFN> USING NEW_PROJECT_REC ON NEWPROJ; 


'. Edit the record definition to change the name of the record and add the 
desired field definitions. Note that with EDIT BACKUP in effect, 
DATATRIEVE does not delete the original record definition when you exit 
the edit buffer. 


DTR> EDIT PROJECT_REC 
1 REDEFINE RECORD PROJECT_REC USING 


* C 
REDEFINE RECORD NEW_PROJECT_REC USING 
01 NEW_PROJECT_REC. 
03 PROJ_CODE PIC 9(3) QUERY_NAME IS NUM. 


03 PROJ_NAME PIC X(10) QUERY_NAME IS NAME 
03 PROJ_COST PIC 9(6)V99 EDIT_STRING IS $$$, $$9.99. 
03 MANAGER_NUM PIC 9(5). 
03 MGR_NAME PIC X(15). 
* exit 


[Record NEW_PROJECT_REC is 40 bytes long] 


DTR> 


Define a new data file for NEW PROJECTS. This example creates an 
indexed file to replace the sequential file associated with PROJECTS: 


DTR> DEFINE FILE FOR NEW_PROJECTS KEY=PROJ_CODE 
DTR> 


Restructuring Data 10-3 


You are now ready to transfer the data from the old domain to the new one. 


10.3. Entering Data in the New File 


To transfer data from the old domain to the new one, you must first ready both 
domains. Ready the new domain for WRITE or EXTEND access, and ready the 
old one for READ access. Then use the Restructure statement to transfer the 
data: . 


DTR> READY NEW_PROJECTS WRITE 
DTR> READY PROJECTS 

DTR> NEW_PROJECTS = PROJECTS 
DTR> 


For each field name in NEW PROJECT REC that matches a field name in 
PROJECTS REC, the Restructure statement transfers field values from each 
record in PROJECTS to a record in NEW PROJECTS. For a field in the new 
record definition that does not match a field in the old one, DATATRIEVE 
initializes the field according to its data type and its field definition. 


If the field has a DEFAULT VALUE clause, DATATRIEVE initializes the field 
with the default value. If the field has a MISSING VALUE clause and no 
DEFAULT VALUE clause, DATATRIEVE initializes the field with the missing 
value. If the field has neither a DEFAULT VALUE clause nor a MISSING 
VALUE clause, DATATRIEVE initializes a numeric field as 0 and an alphabetic 
or alphanumeric field as spaces. 


The data file associated with your new domain now has records in it. When you 
display the contents of the new domain on your terminal, you can see the two new 
fields and the same values contained in the PROJECTS domain: 


DTR> PRINT NEW_PROJECTS 


PROJ PROJ PROJ MANAGER MGR 
NUM NAME COST NUM NAME 
002 GROUNDS $0.00 00006 
005 BUILDING 2 $0.00 00003 
008 SHED $0.00 00002 
018 RESEARCH $0.00 00006 
037 PUB REL $0.00 00008 
073 MATERIALS $0.00 00002 


DTR> 
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0.4 Creating Record Subsets 


ou can create the new domain from a subset of the old domain’s records. You 
recify the limiting conditions in the RSE of the Restructure statement. For 
‘ample, you can limit a domain to the projects of two managers: 


R> READY NEW_PROJECTS WRITE 

R> READY PROJECTS 

R> NEW_PROJECTS = PROJECTS WITH MANAGER_NUM EQ 2, 6 
R> PRINT NEW_PROJECTS 


OJ PROJ PROJ. MANAGER MGR 
M NAME COST NUM NAME 
2 GROUNDS $0.00 00006 

8 SHED $0.00 00002 

8 RESEARCH $0.00 00006 

3 MATERIALS $0.00 00002 

R> 


te that the Restructure statement relies on record definitions having the same 
ld names. If you want to change field names, you can either edit the record 
finition after the restructure operation or use a STORE USING statement 
stead of the Restructure statement. The chapter on Designing Better Records 
ntains an example of STORE USING to restructure data. 


.5 Combining Data from Two or More Domains 


\other reason for creating a new domain is to combine the data from two or 
re existing domains. If you frequently use the same CROSS clause to form 
‘ord streams and you cannot use a view domain because you need to store 
‘ords in the domain, you can define a new domain to meet your needs. 


r example, when you enter data in the file of NEW PROJECTS, you can also 
‘lude the names of the managers from another domain, MANAGERS: 


t> SHOW MANAGERS, MANAGER_REC 
fAIN MANAGERS USING MANAGER_REC ON MGR; 
‘ORD MANAGER_REC USING 


MANAGER. 
03 MANAGER_NUM PIC 9(5). 
03 MGR_NAME PIC X(8). 


'> 


splaying the records from MANAGERS shows that values in the field 
\NAGER NUM correspond to the values in the MANAGER NUM field in the 
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domain PROJECTS: 


DTR> READY MANAGERS; PRINT MANAGERS 


MANAGER MGR 
NUM NAME 


00002 BLOUNT 
00003 GERBLE 
00005 GORFF 
00006 PUFFNER 
00008 FEBNELL 


DTR> 


Using a CROSS clause in the RSE of the Restructure statement, you can match 
MANAGERS records with the corresponding PROJECTS records. The OVER 
clause allows you to match those records with matching values in the 
MANAGER NUM fields. You must ready all three domains to transfer the data 
from PROJECTS and MANAGERS to NEW PROJECTS: 


DTR> READY NEW_PROJECTS WRITE 

DTR> READY PROJECTS 

DTR> READY MANAGERS . 

DTR> NEW_PROJECTS = PROJECTS CROSS MANAGERS OVER MANAGER_NUM 
DTR> 


Displaying the records in NEW PROJ ECTS shows the result of the Restructure 
with a CROSS clause in the RSE. Notice that the value of PROJ COST in each 


record is 0: the field did not exist in either of the source domains: 


DTR> PRINT NEW_PROJECTS 


PROJ PROJ PROJ MANAGER MGR 
NUM NAME COST NUM NAME 
002 GROUNDS $0.00 00006 PUFFNER 
005 BUILDING 2 $0.00 00003 GERBLE 
008 SHED $0.00 00002 BLOUNT 
018 RESEARCH $0.00 00006 PUFFNER 
037 PUB REL $0.00 00008 FEBNELL 
073 MATERIALS $0.00 00002 BLOUNT 
DTR> 


10.6 Using the Alias Clause to Restructure a Domain 


You can use the Alias clause to restructure a domain. When you use this method 
you can make use of the difference between the record definition in the CDD and 
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she record definition controlling a readied domain in your workspace. For exam- 
dle, when you ready YACHTS as OLD YACHTS, the record definition YACHT is 
issociated with the data file YACHT.DAT. If you then edit and redefine the for- 
nat of the record definition YACHT, this change to the record is not associated 
vith the readied domain (OLD YACHTS). It is only associated with YACHTS the 
1ext time you ready the domain. 


[his method lets you make use of the difference between the record definition 

n the CDD and the record definition controlling a readied domain in your 
vorkspace. The change in the record definition does not take effect until you use 
he FINISH command to finish the domain and the READY command to ready it 
gain. Simply readying the domain again does not activate the new record 
lefinition. 


7ou can make use of this fact if you want to change a record definition or change 
he type of file organization of a domain’s data file. Follow these steps to change 
he record definition or file type without redefining the domain. In both cases, you 
efine a new data file and transfer the data with the Restructure statement: 


1. Ready the domain as an alias: 


DTR> READY YACHTS AS OLD_YACHTS 
DTR> SHOW READY 
Ready sources: 
OLD_YACHTS: Domain, RMS sequential, protected read 
<CDD$TOP . INVENTORY . YACHTS; 1> 
No loaded tables. 


DTR> 
», Change the record definition with the EDIT record-path-name command, 
creating a later version of the same record definition. 


}. Define a new data file for the domain. This creates a new version of the file 
associated with the readied domain but does not interfere with the link 
between the domain you already readied and the original version of the data 
file. Do not use the SUPERSEDE option of the DEFINE FILE command: 


DTR> DEFINE FILE FOR YACHTS KEY = TYPE 
DTR> 


Ready the domain as a different alias and specify the WRITE access mode. 
This READY command uses the new version of the record definition and 
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opens the new data file created by the DEFINE FILE command: 


DTR> READY YACHTS AS NEW_YACHTS WRITE 
DTR> SHOW READY 
Ready sources: 
NEW_YACHTS: Domain, RMS indexed, protected write 
<CDD$TOP . INVENTORY. YACHTS; 1> 
OLD_YACHTS: Domain, RMS sequential, protected read 
<CDD$TOP . INVENTORY . YACHTS; 1> 
No loaded tables. 


DTR> 


Now use the Restructure statement to move the data from the original data 
file to the’ new one. DATATRIEVE transfers data from fields in the original 
data file into fields with the same names in the new data file. 


DTR> NEW_YACHTS = OLD_YACHTS 
DTR> 


10.7 Changing the Organization of a Data File 


You can also use the Alias clause of the READY command to change the organi- 
zation of a data file associated with a domain. This example replaces the indexed 
data file associated with YACHTS with a sequential data file: 


DTR> 
-DTR> 
DTR> 
DTR> 
DTR> 
[113 
DTR> 


READY YACHTS AS OLD 
DEFINE FILE FOR YACHTS 
READY YACHTS AS NEW WRITE 
NEW = OLD 

FIND NEW 

records found] 


10.8 Further Examples of Restructuring Domains 


This example defines an indexed file for a new domain based on FAMILY REC. 
The records of the source domain, FAMILIES, are in a sequential file. The com- 
plex Boolean expression in the RSE of the Restructure statement limits the num 
ber of records transfered to the new domain. The new domain contains the 
records of only those families who have no kids younger than 15: 


DTR> 
DTR> 
DTR> 
DTR> 
DTR> 
DTR> 


READY FAMILIES 

DEFINE DOMAIN NEWFAMS USING FAMILY_REC ON FAMS; 
DEFINE FILE FOR NEWFAMS MAX, KEY = MOTHER (DUP) 
READY NEWFAMS WRITE 

NEWFAMS = FAMILIES WITH NOT ANY KIDS WITH AGE LE 15 
FIND NEWFAMS 


{8 records found] 


DTR> 


FIND FAMILIES 


[16 records found] 


DTR> 
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The next example defines a new domain called YACHTS PRICE LIST, which 
contains only the fields TYPE and PRICE from the old YACHT record definition. 
The DEFINE RECORD command shortens the length of the MODEL field from 
en to eight bytes and provides a MISSING VALUE edit string for the PRICE 

‘jeld. The FIND statements following the Restructure statement check the num- 


yer of records transferred and the accuracy of the transfer (with the CROSS 


‘lause in the second FIND). The PRINT statement shows the effect of the new 


MISSING VALUE edit string: 


ITR> DEFINE DOMAIN YACHTS_PRICE_LIST USING YPL_REC ON YPL.DAT; 
ITR> DEFINE RECORD YPL_REC USING 


FN> O01 BOAT. 

FN> 03 TYPE. 

FN> OS BUILDER PIC X(10). 

FN> O5 MODEL PIC X(8). 

FN> 03 PRICE PIC 9(5) MISSING VALUE IS 0 
FN> EDIT_STRING $$$,$$$?"NOT LISTED". 
FN> ; 


Record is 23 bytes long. ] 
TR> DEFINE FILE FOR YACHTS_PRICE_LIST KEY = TYPE 
TR> READY YACHTS_PRICE_LIST AS YPL WRITE 
TR> READY YACHTS 
TR> SHOW READY 
eady sources: 
YACHTS: Domain, RMS indexed, protected read 
<CDD$TOP .DTR32.WAJ. YACHTS; 1> 
YPL: Domain, RMS indexed, protected write 


<CDD$TOP .DTR32.WAJ.YACHTS_PRICE_LIST;1> 
> loaded tables. ; 


[R> YPL = YACHTS WITH LOA GT 35 
[R> FIND YACHTS WITH LOA GT 35 
23 records found] 

(R> FIND YPL 

23 records found] 

"R> FIND A IN YPL CROSS B IN YACHTS OVER 
ooking for field name] 

IN> TYPE WITH A.PRICE NE B.PRICE 
’ records found] 

‘R> FIND YPL WITH PRICE MISSING 
2 records found] 

‘R> PRINT FIRST 3 CURRENT 


UILDER MODEL PRICE 
OCK I. 40 NOT LISTED 
BOT 36 NOT LISTED 
WN EAST 38 NOT LISTED 
R> 
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10.9 Better Data Organization 


DATATRIEVE provides you with many alternative strategies for record design. 
You can save design time and processing time by choosing the best strategy for 
your data. The chapter on designing better records offers suggestions for organiz- 
ing data efficiently at the beginning of the data design process and for reorganiz- 
ing existing data in the most efficient ways. It contains examples of reorganizing 
data with both the Restructure and STORE...USING statements. 
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‘AX DATATRIEVE offers great flexibility in defining records, tables, and 
ariables. There are usually several alternative strategies for organizing your data 
» make data access easier and faster. Before deciding how to define your data, 

-y to determine the types of queries and reports that you want to produce. This 
hapter offers some suggestions for organizing your data in the most efficient 
ays. 


ou may also want to change the organization of existing data. This chapter pro- 
ides examples using DATATRIEVE’s Restructure and STORE USING state- 
ents to reorganize the data. 


eep the following points in mind when organizing or reorganizing data: 


-Consider using flat records rather than hierarchical records for greater ease 
of accessing data. 


Define several related records, rather than one large record containing every 
field. | 


Choose keys carefully to optimize performance for accessing data and joining 
related records. 


Use tables to validate data, to make data entry easier, and to use as little 
storage space as possible. 


Use virtual (COMPUTED BY) fields wherever possible to save storage and 
make data entry easier. 


1.1. Flat Records and Hierarchical Records 


hen defining a record, you can choose to use lists (hierarchies) or to break off 
ch list item into separate records (flat files). It is usually easier to access data in 
it files than in hierarchical files. This point can be illustrated with the sample 
main FAMILIES. 


The data stored in FAMILIES could be organized in flat records or in hierarchical 
records. FAMILIES happens to use a hierarchical record organization, a record 
containing the repeating list field KIDS. Figure 11-1 illustrates the structure of 
the record FAMILY. 


O1 FAMILY 


03 PARENTS O03 NUMBER_KIDS ] 03 KIDS OCCURS 1 TO 10 TIMES 
OG FATHER | 0G MOTHER hed OG EACH _KID 


O98 KID_-NAME 09 AGE 
OG EACH_KID 


O9 KID-NAME 09 AGE 


+ ¢ ¢ 
% e + 


e e 


OG EACH_KID 


OS KID_NAME O93 AGE. 
ZK-0003-' 


Figure 11-1: Structure of a Hierarchical Record 


VAX DATATRIEVE supports lists or hierarchies created using the OCCURS 
clause in record definitions. You can consider the list field to be a small domain 
within each record of the large domain. For example, you can view each record in 
FAMILIES as containing several KIDS “records.” To access one of the KIDS 
“records,” you must do two things: 


e Identify a specific record in FAMILIES. 


e Identify the KIDS “record” within that FAMILIES record. 
In the following example, two FOR loops are required to modify ELLEN’s age: 


DTR> FOR FAMILIES WITH FATHER = "JIM" AND MOTHER = "LOUISE" 
CON> FOR KIDS WITH KID_NAME = "ELLEN" 

CON> MODIFY AGE 

Enter AGE: 26 

DTR> 


Sometimes nested FOR loops are not sufficient to access data stored in a list. If 
you want to sort all the records in FAMILIES by the age of the children, you 
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ust first flatten the records in FAMILIES with the CROSS clause: 


R> FOR FAMILIES CROSS KIDS SORTED BY AGE 
N> PRINT PARENTS, KID_NAME, AGE 


KID 

FATHER MOTHER NAME AGE 
EARMAN SARAH DAVID 0 
HN ELLEN CHRISTOPHR 0O 
NIE ANNE BRIAN 0 
NIE ANNE SCOTT 2 
M ANN RALPH 3 

4 


M ANNE PATRICK 


R> 


) alternative to this complex syntax and high performance overhead is to orga- 


ze the records in a flat file to begin with, as Figure 11-2 shows. 







O1 FAMILY _FLAT_REC 


03 PARENTS 03 EACH_KID 
. OS MOTHER 0S KIDUNAME 
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15 FATHER 





lis is the complete record definition of FAMILY FLAT REC: 


R> SHOW FAMILY_FLAT_REC 
SORD FAMILY_FLAT_REC USING 
FAMILY_REC. 
03 PARENTS. 
O5 FATHER PIC X(10). 
O5 MOTHER PIC X(10). 
03 EACH_KID. 
O5 KID_NAME PIC X(10). 
05 AGE PIC 99 
EDIT_STRING IS 29. 


> 


Designing Better Records 


11-3 


Each record of FAMILY FLAT has elementary fields for FATHER, MOTHER, 
KID NAME, and AGE. This simplifies the task of modifying a child’s age. For 
example, to modify Ellen’s age: 


DTR> MODIFY AGE OF FAMILY_FLAT WITH FATHER = "JIM" AND 
CON> KID_NAME = "ELLEN" 


To sort by the age of children, you can enter: 
DTR>PRINT FAMILY_FLAT SORTED BY AGE 


Because FAMILY FLAT does not have hierarchical records like FAMILIES, 
VAX DATATRIEVE does not have to flatten records before sorting them. This 
gives you better performance along with easier access to data. There are addi- 
tional costs, however. for storing the same parent information with each child in 
the family. This issue is discussed in Chapter 12. 


11.1.1 Restructuring a Hierarchical File to a Flat File 


You can use a Restructure statement to convert the records in FAMILIES to 
FAMILY FLAT. After defining the domain, record, and file for FAMILY FLAT, 
enter the following statements: 


DTR> READY FAMILIES 
DTR> READY FAMILY_FLAT WRITE 
DTR> FAMILY_FLAT = FAMILIES CROSS KIDS 


The Restructure statement contains a CROSS clause so that each child is in a 
separate record, paralleling the structure of FAMILY FLAT. A PRINT statemer 
displays the records of FAMILY FLAT: 


DTR> PRINT FAMILY_FLAT 


KID 

FATHER MOTHER NAME AGE 
JIM ANN URSULA 7 
JIM ANN. RALPH 3 
JIM LOUISE ANNE 31 
JIM LOUISE JIM 29 
JIM LOUISE ELLEN 26 
JIM LOUISE DAVID 24 
JIM LOUISE ROBERT 16 


JOHN JULIE ANN 29 


(continued on next page) 
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AROLD SARAH HAROLD 35 


AROLD SARAH SARAH 27 
DWIN TRINITA ERIC 16 
DWIN TRINITA SCOTT 11 
TR> 


low all of the data for parents and their children has been stored in 

'AMILY FLAT, but one problem remains. In joining FAMILIES on the 

st field KIDS, you leave out any records of FAMILIES with parents but no 
hildren. In fact, there is one such record in FAMILIES: 


[R> PRINT FAMILIES WITH NOT ANY KIDS 


NUMBER KID 
FATHER MOTHER KIDS NAME AGE 


JB DIDI .¢) 


ut this record from FAMILIES is not included in the record stream formed by 
AMILIES CROSS KIDS, because the KIDS list is empty. As a result, the 
estructure statement does not store the data about ROB and DIDI in 

AMILY FLAT: 


[(R> FIND FAMILY_FLAT WITH FATHER = "ROB" 
) records found] 
(R> 


o include records of parents without children in FAMILY FLAT, you need a 
»parate storing operation: 


"R> FOR A IN FAMILIES WITH NOT ANY KIDS 
ooking for statement] 
IN> STORE FAMILY_FLAT USING PARENTS = A.PARENTS 


ow the transfer of data from FAMILIES to FAMILY FLAT is complete: 


‘R> PRINT FAMILY_FLAT WITH FATHER = "ROB" 


| KID 

FATHER MOTHER NAME AGE 
IB DIDI 

oe 
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11.1.2 Defining Several Smaller Related Records 


Though VAX DATATRIEVE lets you define very large records, you may be bet- 
ter off dividing a large record into several smaller related records. If you include 
all the fields in one large record, you can access any portion of the-data by 
readying only one domain. However, if you need information from only one field, 
DATATRIEVE still must read through the large record. 


Another problem with large, all-inclusive records is that several records can dupli- 
cate the same information. Not only is this expensive to store, but you may have 
problems when updating data if you do not change the information in all the rel- 
evant records. 


This problem could occur with the FAMILY FLAT records discussed in the pre- 
vious section. Parent information is stored in each child’s record. If the marital 
status of the parents should change, each of the children’s records would have to 
be updated. You can avoid this problem by storing parent data in one domain 
(FOLKS) and children’s data in a second domain (CHILDREN). 


The two domains could each have an ID field, representing an ID assigned to eac! 
set of parents. In the FOLKS domain, you store the ID along with the parents’ 
names. In the CHILDREN domain, you store the parent ID along with the 
children’s names. The record definitions of FOLK REC and CHILD REC follow: 


DTR> SHOW FOLK_REC 
RECORD FOLK_REC USING 
O01 FOLK_REC. 
03 ID PIC 99 
EDIT_STRING IS 29. 
03 PARENTS. 
OS FATHER PIC X(1i0). 
O&5 MOTHER PIC X(10). 


DTR> SHOW CHILD_REC 
RECORD CHILD_REC USING 
O1 CHILD_REC. 
03 ID PIC 99 
EDIT_STRING IS Z9. 
03 KID_NAME PIC X(10). 
03 AGE PIC 99 
EDIT_STRING IS Z9. 


DTR> 
When you need information about both parents and children, you can join the 
FOLKS records with the CHILDREN records over the common ID field. Figure 


11-3 illustrates the result of this relational join. The boldface lines enclose the 
suggested key fields. oa: 
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FOLK_REC } CHTLD-REG REEL 


ee fo — ne 


FOLKS CROSS CHILDREN OVER ID 


FATHER MOTHER one] ace 


jure 11-3: Joining FOLKS and CHILDREN with CROSS 





FATHER 
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1.3 Restructuring a Large Record into Several Smaller Records 


A\TATRIEVE simplifies the conversion of large records to several smaller 
‘ords. This point is illustrated by converting the larger records of 
\MILY FLAT to the smaller records of FOLKS and CHILDREN. 


ith FOLKS and CHILDREN have an ID field that indicates a unique set of par- 
ts. Because FAMILY FLAT has duplicate occurrences for sets of parents (one 
‘each of their children), you need to determine the unique sets of parents in the 
cords of FAMILY FLAT before assigning ID values. Use the REDUCED TO 
use in the record selection expression to find the unique values. Then use a 
‘ORE USING statement to store values in FOLKS, assigning values for ID 
th RUNNING COUNT. The following DATATRIEVE session uses these 
itements: 


%> READY FAMILY_FLAT 

t> READY FOLKS WRITE 

t> FOR A IN FAMILY_FLAT REDUCED TO PARENTS 
> STORE FOLKS USING 


\> BEGIN: 

{> ID = RUNNING COUNT 
{> FATHER = A.FATHER 
\> MOTHER = A.MOTHER 
I> END 


this example shows, the STORE USING statement is another way to 
structure a domain. A PRINT statement displays the records in the new 
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domain FOLKS: 
DTR> PRINT FOLKS 


ID 


OONOOPWDHE 


FATHER 


ARNIE 
BASIL 
EDWIN 
GEORGE 
HAROLD 
JEROME 
JIM 
JIM 
JOHN 
JOHN 
ROB 
SHEARMAN 
TOM 
TOM 


DTR> 


To store records in the related CHILDREN domain, you need the ID and parent 
data from FOLKS and the children data from FAMILY FLAT. The record selec- 
tion expression FAMILY FLAT CROSS FOLKS OVER PARENTS gives you all 
the necessary information. You can use this RSE as the right-hand part of a 
Restructure statement for the CHILDREN domain: 

DTR> READY FAMILY_FLAT, FOLKS 

DTR> READY CHILDREN WRITE 

DTR> CHILDREN = FAMILY_FLAT CROSS FOLKS OVER PARENTS 


A PRINT statement displays the records in the new CHILDREN domain: 


MOTHER 


ANNE 
MERIDETH 
TRINITA 
LOIS 
SARAH 
RUTH 
ANN 
LOUISE 
ELLEN 
JULIE 
DIDI 
SARAH 
ANNE 
BETTY 


DTR> PRINT CHILDREN 


ID 


ND Dee 


KID 
NAME 


SCOTT 
BRIAN 
BEAU 
BROOKS 
ROBIN 


DAVID 
PATRICK 
SUZIE 
MARTHA 
TOM 


DTR> 
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AGE 


2 
0 
28 
26 
24 


Nw 
NOOP OO 


lote that for ID number 11, a record was stored without a child’s name. This is 
1e record for ROB and DIDI, the only couple in the database without children. 
‘ecause this record is stored in CHILDREN, DATATRIEVE is able to match a 
‘OLKS record and a CHILDREN record for ROB and DIDI. As a result, 
\ATATRIEVE includes information about ROB and DIDI when the FOLKS and 
‘HILDREN domains are joined over the ID field: 


[R> FOR FOLKS CROSS CHILDREN OVER ID 
JN> PRINT FATHER, MOTHER, ID, KID_NAME, AGE 


KID 
FATHER MOTHER ID NAME AGE 
NIE ANNE 1 SCOTT 2 
iNIE ANNE 1 BRIAN 0 
ASIL MERIDETH 2 BEAU 28 
JB DIDI 11 0 
[R> 


1.1.4 Creating a Hierarchical View of Flat Records 


ou can also use a view domain to display data in the FOLKS and CHILDREN 
omains. By using two OCCURS FOR clauses in the view domain definition, you 
‘eate a hierarchical relationship between FOLKS and CHILDREN. Printing the 
cords in the view domain gives a display similar to the original FAMILIES 
omain. 


he following example shows a view domain, FAMILY VIEW, that simulates the 
‘ructure of the original hierarchical domain FAMILIES using the flat domains 
OLKS and CHILDREN: 


'R> SHOW FAMILY_VIEW 
)MAIN FAMILY_VIEW OF FOLKS, CHILDREN USING 
. PARENTS, OCCURS FOR FOLKS. 
03 FATHER FROM FOLKS. 
03 MOTHER FROM FOLKS. 
03 KIDS OCCURS FOR CHILDREN WITH ID = FOLK_REC.ID. 
O5 KID_NAME FROM CHILDREN. 
O& AGE FROM CHILDREN. 


(continued on next page) 
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DTR> PRINT FAMILY_VIEW 


KID 

FATHER MOTHER NAME AGE 
ARNIE ANNE SCOTT 2 
BRIAN 0 

BASIL MERIDETH BEAU 28 
~ BROOKS 26 

ROBIN 24 

JAY 22 

WREN 17 

JILL 20 

EDWIN TRINITA ERIC 16 
SCOTT 11 

ROB DIDI 0 
SHEARMAN SARAH DAVID 0) 
TOM ANNE PATRICK 4 
SUZIE 6 

TOM BETTY MARTHA 30 
TOM 27 

DTR> 


11.2 Choose Keys for Optimization 


DATATRIEVE performs best if you choose key fields for indexed records wisely. 
This is especially important when you use the CROSS clause. Chapter 12 in this 
manual has more information on key optimization. 


11.3 Using Tables 


Tables are useful in record definitions both for validation and for saving storage 
space. The record for PERSONNEL can be improved by using tables. The current 
definition of PERSONNEL REC contains this field definition: 


O05 EMPLOYEE_STATUS PIc IS X(11) 
QUERY_NAME IS STATUS 
QUERY_HEADER IS "STATUS" 
VALID IF STATUS EQ "TRAINEE", "EXPERIENCED". 


EMPLOYEE STATUS is an 11-byte field that takes only two values: TRAINEE 
or EXPERIENCED. Rather than storing the 11 bytes for each record, you could 
use a table to translate the value for a 1-byte status code. This device saves 10 
bytes of storage per record and reduces time for data entry. 
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‘ere is a definition for the dictionary table STATUS TABLE: 


[R> DEFINE TABLE STATUS_TABLE 
*N> E EXPERIENCED 
*N> T ; TRAINEE 

*N> END_TABLE 


ou can now edit PERSONNEL REC, deleting the EMPLOYEE STATUS field 
1d adding two new fields that reference the table. EMP STATUS CODE vali- 

ates entries for the status code by checking the table. EMP STATUS, a virtual 
eld, translates these code entries to either ”EXPERIENCED” or “TRAINEE”: 


05 EMP_STATUS_CODE PIC X 
QUERY_NAME IS S_CODE 
VALID IF EMP_ STATUS_ CODE IN STATUS_TABLE. 


0&5 EMP_STATUS COMPUTED BY 
EMP_STATUS_CODE VIA STATUS_TABLE. 


ecause the new definition defines a record with 10 fewer bytes, you need to 
»fine a new file for PERSONNEL. The following procedure illustrates how to 
>fine a new file for PERSONNEL and restructure the data to match the new 
‘cord definition with the STORE USING statement: 


"R> SHOW RESTRUCTURE_PERSONNEL 
t{OCEDURE RESTRUCTURE_PERSONNEL 
‘ADY PERSONNEL AS OLD 
(FINE FILE FOR PERSONNEL KEY = ID 
'ADY PERSONNEL AS NEW WRITE 
wR O IN OLD STORE N IN NEW USING 
BEGIN 
N.ID = 0.ID 
CHOICE 
0.EMPLOYEE_STATUS = "EXPERIENCED" THEN 
N.EMP_STATUS_CODE = "E" 
O.STATUS = "TRAINEE" THEN 
N.EMP_STATUS_CODE = "T" 
END_CHOICE 
N.FIRST_NAME = 0.FIRST_NAME 
N.LAST_NAME 0.LAST_NAME 
N.DEPT = 0.DEPT 
N.START_DATE = O.START_DATE 
N.SALARY = 0.SALARY 
N.SUP_ID = 0.SUP_ID 


END 
ID_PROCEDURE 


‘R> 


1.4 Using COMPUTED BY Fields 


1e revised definition PERSONNEL REC uses a COMPUTED BY field to trans- 
te values by using a table. COMPUTED BY fields save storage space and can 
1p ensure accurate data. 
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11.4.1 Computing Age 


You can use COMPUTED BY fields to perform date calculations. Instead of 
entering a value for a person’s age, you can enter a value for the birth date. Then 
you can define a COMPUTED BY field to calculate the age. 


For example. FAMILIES and FAMILY FLAT contain an AGE field. To keep the 
value of AGE accurate. you need to update the field continually. Instead, mee 
could substitute the following two fields: 


O& BIRTH_DATE USAGE IS DATE. 


O5 AGE COMPUTED BY ("TODAY" - BIRTH_DATE)/365.25 
EDIT_STRING IS 229. 


TODAY is a date value expression that always takes the value of the current sys- 
tem date. Note that the factor 365.25 takes account of leap years. 


11.4.2 Quarterly Summaries 


You can also use COMPUTED BY fields to compute the fiscal quarter from a 
date value. The following examples use the domain CURRENT SALES. The 
record includes a field for the salesperson’s ID, the date of the sale, and the 
amount of the sale. Figure 11-4 illustrates the structure of the record. 











O1 CURRENT_REC 


03 SALES_DATE 03 AMOUNT 


03 ID 
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Figure 11-4: Structure of CURRENT REC 


The record definition is: 


DTR> SHOW CURRENT_REC 
RECORD CURRENT_REC USING 
01 CURRENT_REC. 
03 ID PIC IS 9(5). 
03 SALES_DATE USAGE DATE. 
03 AMOUNT PIC IS 9(5)V99 
EDIT_STRING IS $$$,$$$.99. 


DTR> 
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(ou can add several COMPUTED BY fields to the record definition to calculate 
he fiscal quarter, quarterly sales, and yearly sales. The QTR field calculates the 
iscal quarter from the date field SALES DATE through a dictionary table: For 
xample: 


O05 SALES_DATE USAGE IS DATE. 

OS QTR COMPUTED BY 
(FORMAT SALES_DATE USING NN) VIA QTR_TABLE 
EDIT_STRING IS "Q"9. 


‘the FORMAT value expression in QTR returns the numerical value for the 
1onth of SALES DATE. (For more information on FORMAT value expressions 
ee the chapter on defining and calculating values in the VAX DATATRIEVE 
Zandbook and the chapter on value expressions in the VAX DATATRIEVE 
teference Manual.) DATATRIEVE evaluates the COMPUTED BY clause, look- 
ig up this value in a table and finding the numerical value for the fiscal quarter. 
YATATRIEVE then displays this value, preceding the quarter number with the 
tter Q. The table QTR TABLE is defined as: 


TR> SHOW QTR_TABLE 

ABLE QTR_TABLE 
QUERY_HEADER IS "QTR" 

EDIT_STRING IS 9 


1 3 
2 3 
3 3 
4 4 
5 4 
6 4 
cf 1 
8 t 
9 1 
10 2 
11 2 
12. 3 2 
ID_ TABLE 


[R> 


he preceding table assumes that the first quarter begins on July 1, the second 
1 September 1, and so on. Different tables may be appropriate depending on an 
‘ganization’s official calendar. If quarter breaks do not occur on the first of the 
ionth, you may need a table that associates a quarter number with each of the 
35 days of the year. When you look up the value in such a table, use (FORMAT 
TART DATE USING JJJ) as the code field. 


he CHOICE or IF-THEN-ELSE value expressions increase the flexibility of 
OMPUTED BY fields because you can assign values based on conditional tests. 
ou might want to display the sales amounts for each quarter in a separate col- 
nn. You could define the following four virtual fields for the sales of different 
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quarters: 
O5 Q1i_SALES COMPUTED BY IF QTR EQ 1 THEN AMOUNT ELSE 0. 
O05 Q2_SALES COMPUTED BY IF QTR EQ 2 THEN AMOUNT ELSE 0. 
O5 Q3_SALES COMPUTED BY IF QTR EQ 3 THEN AMOUNT ELSE O. 
O5 Q4_SALES COMPUTED BY IF QTR EQ 4 THEN AMOUNT ELSE 0. 


The values of the virtual fields for quarterly sales are either 0 or the sales 
amount, depending on the value for QTR. 


You can also include a COMPUTED BY field in the record to calculate total sales: 


O05 TOTAL_SALES COMPUTED BY 
(Q1_SALES + Q2_SALES + Q3_SALES + Q4_SALES). 


Now you can produce the desired output by entering a SUM statement: 


DTR> SHOW SUMMING 
PROCEDURE SUMMING 
READY CURRENT_SALES 
FIND CURRENT_SALES 


SUM Q1_SALES ("Qi") USING $$$$,$$$.$$ , 
Q2_SALES ("Q2") USING $$$$,$$$.$$ , 
Q3_SALES ("Q3") USING $$$$,$$$.$$ , 
Q4_SALES ("Q4") USING $$$$,$$$.$$ , 
TOTAL_SALES ("TOTAL") USING $$$$,$$$.$$ BY ID 
END_PROCEDURE 
DTR> :SUMMING 
ID Qi Q2 Q3 Q4 TOTAL 
11111 $2,150.91 $2,807.11 $2,748.39 $2,389.90 $10,096.31 
12345 $7,805.69 $3,801.44 $9,973.94 $8,672.99 $30,254.06 
22222 $5,693.29 $3,836.24 $7,274.76 $6,325.88 $23,130.17 
23456 $10,311.18 $1,447.40 $13,175.40 $11,456.87 $36,390.85 
33333 $7,679.00 $6,854.45 $9,812.05 $8,532.22 $32,877.72 
34567 $2,338.91 $14,294.89 $2,988.61 $2,598.79 $22,221.20 
44444 $8,868.17 $10,890.45 $11,331.55 $9,853.52 $40,943.69 
45678 $8,999.99 $11,339.01 $11,499.99 $9,999.99 $41,838.98 
55555 $23,288.42 $1,979.92 $29,757.42 $25,876.02 $80,901.78 
56789 $11,111.06 $14,197.04 $14,197.46 $12,345.62 $51,851.18 
66666 $9,000.01 $21,832.99 $11,500.01 $10,000.01 $52,333.02 
77777 $6,593.10 $30,463.98 $8,424.52 $7,325.67 $52,807.27 
88888 $4,500.00 $38,694.00 $5,750.00 $5,000.00 $53,944.00 
99999 $4,499.99 $44,249.51 $5,749.99 $4,999.99 $59,499.48 
$112,839.72 $206,688.43 $144,184.09 $125,377.47 $589,089.71 
DTR> 


Note that this procedure uses the SUM statement to Beperate totals across each 
row for the different ID numbers. 
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Improving DATATRIEVE Performance 12 


\ATATRIEVE performance depends on many factors. Among them are file 
rganization, selection of keys, and forming queries that take advantage of 
ey optimization. Here are some helpful hints and techniques that can reduce 
IATATRIEVE’s response time. 


2.1 Choosing a File Organization 


ATATRIEVE allows you to define indexed or sequential files for your data. 
equential files require less storage, but DATATRIEVE must search records one 
y one according to their physical order in the file. This organization may be opti- 
ial in certain cases. For example. a domain’s records may contain a field for the 
irrent date, and so records are physically arranged in the order in which they 
ere stored. If you access groups of records in chronological order, you may find 
iis organization efficient. 


t other cases, your access needs may not be suited to this type of physical orga- 
zation. You may need to access a group of records with some common charac- 
ristic that is distributed throughout the file. If the records are stored in a 
‘quential file, DATATRIEVE may have to read all the records to find the ones 
iat are requested. You also may want to erase records from the file. Although 

yu can modify all the fields in a record from a sequential file to contain spaces or 
‘ros, you cannot use DATATRIEVE to erase a record from a sequential file. 


| these cases, an indexed file is probably a better choice. Although indexed files 
quire more storage. they provide DATATRIEVE with an index based on one or 
ore key fields. To retrieve records, DATATRIEVE may be able to perform a fast 
arch through the key-based index, rather than an exhaustive search through 

e records. 


your data is stored in an indexed file, you should structure queries to take 
lvantage of keyed access. This enables DATATRIEVE to use the indexes to the 
e. The next sections provide guidelines to help you do this. 
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12.1.1. Choosing the Primary and Alternate Keys 


When defining data, try to decide which field of the record is likely to be named 
most often in queries. Make that field the primary key of an indexed file for the 
domain. For example, if you are setting up a PERSONNEL domain, you might 
predict that most users will seek information on an employee based on his or her 
ID. In that case, make the ID field the primary key. 


It is also desirable that the primary key be unique. That is, the primary key 
should be sufficient to identify the record. This is the default for primary keys in 
DATATRIEVE. Though it is legal in DATATRIEVE to have duplicate values for 
the primary key, too many duplicates slow performance so that a search of such a 
file may even take longer than a search of a sequential file. Allowing duplicate val: 
ues can also create very large files. 


DATATRIEVE does not allow you to change the value of a primary key field. 
Therefore, do not select as a primary key any field you expect to update. (If you 
must change the value in a primary key, you have to erase the record and store it 
again.) 


If the best field for the primary key does not uniquely identify the record. find 
another field such that the two fields jointly can determine the record. You can 
then designate a group field, encompassing the two fields, as the primary key. Fo 
example, in the YACHTS domain, the group field TYPE (consisting of BUILDEF 
and MODEL) is the primary key, uniquely determining each record in YACHTS. 


If you use a group field as a primary key, keep in mind that DATATRIEVE can 
perform keyed access only on the first elementary field within the group field. 
For example, DATATRIEVE optimizes on the BUILDER field of YACHTS, the 
first elementary field of TYPE. But DATATRIEVE cannot do keyed access on 
the second elementary field. MODEL. Any queries based on MODEL require 
DATATRIEVE to do an exhaustive search through the records in YACHTS. 


In addition, group field keys should not contain numeric items. DATATRIEVE 
cannot do keyed access on a numeric elementary field when it is part of a multipl 
field key. 


If there are other fields that will be used often in queries, you can define them as 
alternate keys. Alternate keys can have duplicate values. However, if you expect 
to have many duplicate values for a field, do not define it as a key; access can be 
faster and the file is smaller when the field is not a key. 


Try to keep your index structure as simple as you can. Defining many alternate 
key fields that you expect to update frequently can cause performance problems 
later on. RMS must allocate disk space for your file’s index just as it allocates 
storage for your file’s data. Frequent updates to key fields mean that your index 
becomes fragmented, stored in many small pieces on different parts of the disk. 
When this happens, DATATRIEVE takes longer to read the index than it did 
when you first created the file. You can correct this problem using RMS utilities. 
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2.2 Designing Files 


a file is large and randomly accesssed, the DEFINE FILE command in 
IATATRIEVE may not result in optimized file design. 


IATATRIEVE, for example, uses a default for an RMS file with the following 
arameters: 


A bucket size of 2 (512-byte) disk blocks 
A contiguous allocation of 3 blocks 
Global buffer count of 0 

File extent of 0 blocks 


he RMS defaults for the DEFINE FILE syntax can cause data in a large 
idexed file to become scattered over your disk, requiring time-consuming I/O 
aput/output) operations. 


wo important considerations are bucket size and index structure. These two file 
‘tributes are related; that is, the smaller the bucket size, typically the deeper the 
dex structure. Frequently, a major problem is that bucket size is too large, and 
1e resulting index structure is too flat. 


bucket is the unit of transfer between storage devices and I/O buffers in mem- 
‘y. A bucket size can be from 1 to 32 blocks (each block containing 512 bytes). 

s a general rule, a small bucket size is optimal for randomly accessed records. 
Iowever, buckets must contain enough room for record insertion or bucket split- 
ng occurs. Bucket splits fragment your data and increase I/O overhead and 

me.) 


flat file has an index structure with only one level. If your file contains more 
ian a few hundred records, a single level index bucket (also called a root bucket) 
in be very large. A large root bucket results in slow access time for a particular 
ita record. Figure 12-1 shows the structure of a flat file. 
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gure 12-1: Flat File Structure 
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Flat file structure and nonoptimal bucket size may be the most significant rea- 
sons for slow access time. A file with two or three levels of index structure and 
smaller bucket size allows you to access data much more quickly. Figure 12-2 
shows a file with two index levels. 
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Figure 12-2: A File with Two Levels of Index 


The following sections describe RMS utilities that help you design a file with 
more optimal bucket size and index depth. They also explain how to optmize 
other file attributes such as global buffers. 

12.2.1 Using EDIT/FDL to Design Your File 


By using the RMS utility File Definition Language (EDIT/FDL) to create a 
large indexed file, you have more flexibility in creating and managing files than 
you have with DATATRIEVE. EDIT/FDL can calculate the file allocation, file 
extent. and bucket size, thus optimizing I/O operations and minimizing file 
fragmentation. 


Before invoking FDL, you need to determine the following about your record and 
data file: 

¢ The total number of records your file will contain 

e The number. size, and data type of your index keys 


¢ The size of the record in bytes 
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1 the next four sections you learn how to invoke EDIT/FDL and use the Design 
hase to describe the attributes of your DATATRIEVE file. 


2.2.1.1 Questions EDIT/FDL Asks -- When you have determined the basic 
icts about your file, you can invoke the EDIT/FDL utility using the following 
ommand line: 


DIT/FDL/SCRIPT = DESIGN filespec.fdl 


his command invokes the prompting form of the FDL utility. EDIT/FDL asks 
wr the following information about your file: 


L. Whether the file is to be indexed 


iw 


The number of indexed keys 


3, How you want EDIT/FDL to display your file design (on a line plot or on a 
surface plot graph) 


!. What kind of emphasis you want EDIT/FDL to use when selecting bucket 
size (smaller buffers [buckets] or flatter files) | 


). The number of records that will be initially loaded in the file 

3}. How you will load records into the file 

’. If the records will be loaded in order of ascending primary key 

}. The number of additional records you will add after the initial file load 

}. If additional records will be added in order of ascending primary key 

). The fill factor of the buckets for each index key | 
Whether the record format is fixed or variable 

?, The mean and maximum record size in bytes 

}. The data type and length of each field 

|. If you will allow duplicates in the key field 

. If you want global buffers 


1. - The bucket size you want to select from the three choices EDIT/FDL 
recommends 


se the help facility within EDIT/FDL to learn more about the utility and the 
lide on tuning VAX RMS for information about file parameters. 
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12.2.1.2 Answers to the EDIT/FDL Prompts -- Your answers to most of the 
questions asked by EDIT/FDL depend on obvious information you have about 
your file, such as record size, number of records, and number of index keys. For 
other questions, the following list suggests answers you can give to the prompts: 


e When prompted for the type of display you would like to see, enter 
LINE PLOT. This tells EDIT/FDL you want the bucket size and index depth 
it selects displayed on a line plot graph. 


(Line_plot Surface_plot) 
Key 0 Design Mode (keyword) [-]: Line_plot 


¢ When prompted for the emphasis you want EDIT/FDL to use in selecting 
bucket size, enter small. This tells EDIT/FDL to use smaller buffers (or 
buckets) rather than flatter files. 


(Smaller_buffers Flatter_files) 
Emphasis for Default Bucket_size (keyword) [SMALL]: Small 


e When prompted for how you will initially load records into the file, answer 
RMS Puts. This tells EDIT/FDL that DATATRIEVE will write records to 
these files. 


e When prompted for the number of additional records you will add, enter 0. 
This question is useful only if you are converting an old data file. 


e- When prompted for fill factor, select 100 (for 100%). DATATRIEVE will fill 
the buckets to maximum capacity when it places data in a file, regardless of 
the figure you enter here. 


e Inthe Final Design phase of EDIT/FDL, when prompted to answer whether 
Global Buffers are desired, answer no. After you exit EDIT/FDL you will cal 
culate a global buffer count using the procedure in the section on Optimizing 
Global Buffers. 


After you answer the initial questions, EDIT/FDL displays a resulting graph that 
shows the relation of bucket sizes to index depths for the file you have described. 
The next section describes this graph, shown in Figure 12-3, and explains how to 
select optimum bucket size. 


— 12.2.1.3 Selecting Optimum Bucket Size -- In EDIT/FDL you select a bucket 
size, first for your file’s primary key structure and then for alternate key struc- 
tures. The bucket size you select for your primary key is also the size of your dati 
buckets. This bucket size then determines the resulting index depth of your file. 
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fter you have selected an emphasis for bucket size (smaller buffers [or buckets] 
ther than flatter files) EDIT/FDL calculates a ratio of bucket size to index 
‘pth. 


displays this ratio on the LINE PLOT graph in EDIT/FDL (Figure 12-3). The 
tio is based on all the questions you-answer, including the size of your records, 

e number of records you will initially load in your file, the number of records you 
pect to add later, and the emphasis you select. 
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jure 12-3: EDIT/FDL Display of Index Depth versus Bucket Size 
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The line graph EDIT/FDL displays shows the ratio of bucket size to index depth 
that results from the file parameters you have selected. For example, the graph i 
Figure 12-3 shows that if you select: 


e A bucket size of 1 block, you get an index depth of 4 

¢ A bucket size of 2 blocks, you get an index depth of 3 

e <A bucket size of 3 through 18 blocks, you get an index depth of 2 

e A bucket size of 19 through 32 blocks, you get in an index depth of 1 

The points at which index size changes are called breakpoints. For example, the 
index depth changes: 

e From 4 to 3 at a bucket size of 2 blocks (the breakpoint is 2) 

e From 8 to 2 at a bucket size of 3 blocks (the breakpoint is 3) 


After viewing the graph, to specify bucket size you must select the Final Design 
(FD) Phase of EDIT/FDL. EDIT/FDL then displays the following information: 


Bucket Size Emphasis: ( Smaller_buffers ) 
Bucket size Breakpoints: (2, 3, 13) 


Key O Bucket size (1-32) [3]: 


It shows the breakpoints (2, 3, and 13) and a default bucket size (3). (The third 
breakpoint, 13, represents a middle point in the range of all the remaining bucke 
sizes and is unimportant for your selection.) 


EDIT/FDL has suggested a bucket size of 3. Note, however, that when you selec 
a bucket size, EDIT/FDL lets you specify any bucket size from 0 to 32. Basically 
though, you want to choose the smallest bucket size (the breakpoint) that corre- 
sponds to 2 or 3 levels of index. In this example, a bucket size of 3 corresponds t 
2 levels of index. Always select the smallest bucket size from the range, in this 
case, 3 buckets rather than 4 to 18. 


Note then, in this example the default bucket size of 3 is acceptable. It is the 
smallest bucket size that corresponds to an index depth of 2. You should always 
check the default bucket size as it may not be the most optimal. 


While many file parameters have a significant effect on file performance, bucket 
size and index depth are the most important. 


After you select a bucket size for your primary key structure (which is also the 
bucket size for your data), you answer the same series of questions about your 
alternate key structure and then select a bucket size for that key. 
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w you can exit EDIT/FDL and create your data file. You should remember the 
ket sizes you selected for primary and alternate keys, as you will use them to 
‘ign global buffers to your file. 


2.2 Creating the Data File 


er you exit EDIT/FDL, it creates a file definition file containing the attributes 
1 described. The file has an extension of .FDL. You use this file to create an 
pty data file with the attributes you described in EDIT/FDL. 


ter the command: 
EATE/FDL = filespec.fdl filespec.dat 


2spec.dat is the empty data file you are creating using the RMS CREATE 
lity. The utility uses the file and record attributes you defined in the FDL 
spec to create this data file. 


2.3 Optimizing Global Buffers 


er you have created the data file, you will want to assign global buffers to your 

. Allocating buffers for indexed files gives RMS more space to store the index 
ucture in memory. Locating a record takes less time if bine record’s index is 
red in one of the buffer areas. 


a general rule, allow enough global buffers to equal the number of index buck- 
in all the key structures (primary plus alternates) plus 5. 


find out how many global buffers to assign, you can run the DATATRIEVE 
cedure provided in this section. It first calculates the number of index buckets 
rour file and then the number of global buffers you should assign. 


S procedure prompts you for: 


The bucket size of a primary key steicnine (calculated in EDIT/FDL) 
The size of the record in bytes 

The number of records in the file 

The fill factor of the primary key (you specified 100 in EDIT/FDL) 


> procedure gives you the number of index buckets RMS provided for the 
nary key structure. It then calculates the number of index buckets in the 
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alternate key structure. It prompts you for: 


The bucket size for the alternate key (calculated in EDIT/FDL) 


1. 
2. The size of the alternate key 
3. The fill factor of the alternate key 


4. The number of duplicates you will allow in the alternate key 


It then calculates the number of index buckets in the alternate key structure, thi 
total number of index buckets, and the global buffer count. 


DEFINE PROCEDURE BUCKETS 
! 


DECLARE 
DECLARE 
DECLARE 
DECLARE 
DECLARE 


DECLARE 
DECLARE 
DECLARE 
DECLARE 
DECLARE 
DECLARE 
DECLARE 
DECLARE 
DECLARE 
DECLARE 
DECLARE 
DECLARE 
DECLARE 
DECLARE 
DECLARE 


DECLARE 


MORE 


PRIMARY_DONE 
KEY_PROMPT 
BUCKET_SIZE 


KEY_SIZE 


REC_SIZE 
NUM_RECS 
REC_OVHD 
KEY_OVHD 
NUM_DUPS 


FILL_FACTOR 


TMP _DRPB 
DRPB 
NUM_DB 
NUM_IB 


TMP _NUM_DB 
TMP_NUM_IB 
PREV_NUM_BUCK 


IRPB 
TOT_IDB 


GRAND_NUM_IDB 


ICOUNT 


PIC X 


VALID IF MORE 


ae) 


I 
PIC X 


CX 
VALID IF DONE 


| 
This procedure calculates the number of index buckets | 
in an RMS indexed file containing FIXED length records. | 
and then specifies a GLOBAL BUFFER count. | 


= ny ; Wyte ; hy ; Wht . 


= wy : Wyte . y" ; Mint . 


VALID IF KEY_PROMPT = "P","A","p", "a", 


PIC 9(2) 


VALID IF BUCKET_SIZE BETWEEN 1 AND 32. 


PIC 9(3) 


VALID IF KEY_SIZE. BETWEEN i AND 125. 


PIC 9(4) 


PIC 9(6). 
PIC 9(2). 
PIC 9(1). 
PIC 9(3). 
PIC 9(3)v99. 
PIC 9(5)V99. 


PIC 9(5) 


PIC 9(5). 
PIC 9(5). 
PIC 9(5)V99. 
PIC 9(5)v99. 
PIC 9(5). 
PIC 9(5). 


PIC 9(5) 


EDIT_STRING IS 22229. 


PIc 9(5) 


EDIT_STRING IS 22229. 


PIC 9. 
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KEY_OVHD = 3 
MORE = "y" 
GRAND_NUM_IDB = 0 
NUM_RECS = 0 
PRIMARY_DONE = "N" 
PRINT " ". 
PRINT 0 2 2 2 2 2 28 28 2822822 RR ROR 2 2 I IE CE RR A CC CC ak IC oC oc 2 oc oe ak ake 
PRINT "x eM 
PRINT "* This procedure calculates the number of index buckets *" 
PRINT "* in an RMS indexed file containing FIXED length records *" 
PRINT "* and then specifies a GLOBAL BUFFER count. *" 
PRINT 0 22k 2k 2 3 2 2 2k ICR I II RO ICICI CRI CRC Re 2k 2k aC ok 2 2k ok a ak 2c 2 ak ak 
WHILE MORE EQ "Y" 
BEGIN 

TOT_IDB = 0 

PRINT " " 

‘CHOICE 

(PRIMARY_DONE EQ "N") THEN BEGIN 


KEY_PROMPT = *."Primary or Alternate key structure (P or A) " 
KEY_PROMPT = FN$UPCASE (KEY_PROMPT) 
END 
ELSE KEY_PROMPT = "A" 
END_CHOICE 
CHOICE 


(KEY_PROMPT EQ "P") THEN BEGIN 
PRIMARY_DONE = "Y" 
BUCKET_SIZE = *." bucket size of the primary key structure (0-32) " 
REC_SIZE = *."record size in bytes (1-9999) " 
KEY_SIZE = *."size of the primary key in bytes (1-125) " 
NUM_RECS = *."number of records in the file (0 - 999,999) " 
FILL_FACTOR = *."fill factor of the primary key structure (0 - 100) " 
FILL_FACTOR = FILL_FACTOR / 100.0 
REC_OVHD = 7 
END 
ELSE BEGIN 
BUCKET_SIZE = *."bucket size of the alternate key struc. (0-32) " 
KEY_SIZE = *."size of the alternate key in bytes (1-125) " 
REC_SIZE = KEY_SIZE 
CHOICE 
(NUM_RECS EQ 0) THEN 
NUM_RECS = *."number of records in the file (0 - 999,999) " 
END_CHOICE 
FILL_FACTOR = *."the fill factor of the alternate key (0 - 100) " 
FILL_FACTOR = FILL_FACTOR / 100.0 
NUM_DUPS = *."the number of dup keys in the alternate key (0 - 100) " 
CHOICE 
(NUM_DUPS EQ 0) THEN REC_OVHD = 9 
ELSE REC_OVHD = (8 + (5 * NUM_DUPS)) 
END_CHOICE 
D 


EN 
END_CHOICE 


Find the floor number of data records per bucket. 


‘MP_DRPB = (((BUCKET_SIZE * 512) * FILL_FACTOR) - 15) / - 
(REC_SIZE + REC_OVHD) 
RPB = FN$FLOOR(TMP_DRPB ) 


(continued on next page) 
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! 
! Find ceiling number of data buckets. 
' 


TMP_NUM_DB = (NUM_RECS / DRPB) + 0.49 
NUM_DB = (TMP_NUM_DB ) 


IRPB = (( (BUCKET. SIZE * 512) * FILL_FACTOR) - 15) / - 
(KEY_SIZE + KEY_OVHD) 
PREV_NUM_BUCK = NUM_DB 


NUM_IB = 0 

ICOUNT = 0 

WHILE (NUM_IB NE 1) 
BEGIN 


ICOUNT = ICOUNT + 1 
! 


! Find ceiling number of index buckets. 
{ 
TMP_NUM_IB = (PREV_NUM_BUCK / IRPB) + 0.49 
NUM_IB = (TMP_NUM_IB ) 
CHOICE 
(NUM_IB GT 1)THEN BEGIN 
TOT_IDB = TOT_IDB + NUM_IB 
PREV_NUM_BUCK = NUM_IB 
END 
END_CHOICE 
END 
TOT_IDB = TOT_IDB + 1 
PRINT " * 


CHOICE 
(KEY_PROMPT EQ "P") THEN 
PRINT "NUMBER OF TOTAL INDEX BUCKETS FOR - 
PRIMARY KEY STRUCTURE ==> ", TOT_IDB(-) ELSE 
PRINT "NUMBER OF TOTAL INDEX BUCKETS FOR ALTERNATE KEY - 
STRUCTURE ==> ", TOT_IDB(-) 
END_CHOICE 
PRINT " " 


PRINT " " 
! 


MORE *."Y to calculate more index structures, N to exit " 

MORE = FN$UPCASE (MORE) 

GRAND_NUM_IDB = GRAND_NUM_IDB + TOT_IDB 

END; 

PRINT " " 

PRINT 882% 2 2425 5 94 2 ee 2 fe 28 2 CE I RC Ce RC RR 2 Ee kek kek 2 oe kc oe oi 2k 2 ok akc 2 a akc akc tt 

PRINT " " 

PRINT "NUMBER OF TOTAL INDEX BUCKETS FOR ALL KEY - 
STRUCTURES ==> ", GRAND_NUM_IDB(-) 

PRINT " " 

! 


' Add 5 to the number of index buckets 
' 


GRAND_NUM_IDB = GRAND_NUM_IDB + 5 
PRINT "Set the GLOBAL BUFFER attribute on - 
the file to ", GRAND_NUM_IDB(-) 
PRINT " " 
PRINT 88 2k 2k 2k 24 25 2k 2k 2 2k 2 2k 2h 2 fe ie 24 ie he ie fe fe 2 oe oc 28g es 2 fe ok ofc 2c fe 2c fc kc kc kc akc os kc ake ok ok 2c oie 2 2k ok 2 2k oie oc oie oie ok ok ok 
PRINT " " 
END_PROCEDURE ; 
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e following example illustrates how the procedure works to calculate the num- 
‘of global buffers you should assign to your file. 


t> : buckets 


HIGGS I ICICI GIGI a ICI a a CARI AR 1K 2 25 kk CR ak 

x 
This procedure calculates the number of index buckets  * 
in an RMS indexed file containing FIXED length records * 
and specifies the number of GLOBAL BUFFERS. * 


er Primary or Alternate key structure (P or A) : P 

ier bucket size of the primary key structure (0-32) : 3 

ier record size in bytes (1-9999) : 1000 

er size of the primary key in bytes (1-125) : 21 

ier number of records in the file (0 - 999,999) : 10000 

er fill factor of primary key structure (0 - 100) : 100 


er Y to calculate more index structures, N to exit : y 
er Primary or Alternate key structure (P or A) : a 

er bucket size of the alternate key structure (0-32) : 2 
er size of the alternate key in bytes (1-125) : 12 

er number of records in the file (0 - 999,999) : 10000 


er fill factor of the alternate key structure (0 - 100) : 100 
er number of dup keys in alternate key structure (0 - 100) : 2 


SSS SS Tl SL SS SS SS SS SS SS SS SSS SS SS LS SE SS SE EE ES SS SS SS SS SS SL SS SS SS SS ee eS 


er Y to calculate more index structures, N to exit : an 
JUSS EES GI EERE EGGS SCISSOR i Raa Kk ako 

BER OF TOTAL INDEX BUCKETS FOR ALL KEY STRUCTURES == 89 
the GLOBAL BUFFER attribute on the file to 94 

FOI ICICI IOI COC OI IO OIG IO IG IOI GIG IR I II ICI a i kei i242 2k 2 


> 


> procedure calculated that there are 83 index buckets for the primary index 
‘in the sample file you described and six index buckets for the alternate key. It 
led five to the total index buckets and arrived at a global buffer count of 94. 
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After you have the correct global buffer count, you can adjust the count using the 
SET FILE/GLOBAL BUFFERS command: 


SET FILE/GLOBAL BUFFERS = n filespec.dat 


12.2.4 Redesign and Maintenance 


It is important to maintain files you use in DATATRIEVE applications, particu- 
larly if they are large indexed files. If you have added or deleted many records, 
changed the number of indexed keys, or adjusted the size of your records, you 
may have a badly fragmented file or a file bucket size or global buffer count that 
may be causing poor I/O performance. 


It is easiest to go through the same set of procedures you used to create your ini: 
tial file. Invoke EDIT/FDL and create a new .FDL file description. Before invok- 
ing EDIT/FDL., you need to know: 


¢ The same information you needed when you first created your file such as 
record size and key size 


e A fill factor for the file you are redesigning 


You may want to use the RMS Analyze Utility to remember such information as 
record size, number of keys, and key sizes. You can enter the ANALYZE com- 
mand as in the following example: 


ANALYZE/RMS FILE Filename.dat 


12.2.4.1. Calculating a Fill Factor -- You should calculate a new fill factor 
before invoking EDIT/FDL. The fill factor is important when redesigning your 
file. The fill factor ensures that when you move the data from your old frag- 
mented file to your new redesigned file, RMS leaves room in the buckets for add 
tional records to be added after you load the file. This room reduces the amount 
bucket splitting that occurs when you add records to the file at a later time. Use 
the following formula to calculate the fill factor: 


Fill Factor = 100 - ((the number of records to be added/ 
(the number of initial records in the file) * 100)) 


For example. if your file contains 10,000 records now and you intend to add 
approximately 1000 more before you redesign again, you would specify a fill fact 
of 90: 


Fill Factor = 100 - ((1000/(10,000) *100)) 
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The easiest way to determine the number of records in your file is by invoking 
DATATRIEVE and entering the statements: 


JTR> READY domain-name 
JTR> PRINT COUNT OF domain-name 


Now that you know the fill factor and the other information for which EDIT/FDL 
prompts you, you can invoke the utility and design a new .FDL file: 
=DIT/FDL/SCRIPT = DESIGN filespec.fdl 

12.2.4.2 Adding Data to the File -- After you redesign your file, you will want 
70 move data from the existing file into a new data file. It is best to use the RMS 


CONVERT utility to load large files. It is much faster than DATATRIEVE and 
oads data more optimally. 


Jse the following command line to create a data file using your new .FDL to 
lescribe the file and to load that new file with data from the old file: 


SONVERT/FDL = filespec.fdl oldfile.dat newfile.dat 


*or more information on file tuning and RMS utilities refer to the guide on tuning 
JAX RMS. | 


12.3 Choosing Optimal Queries 

Jnce you establish the file organization, you should try to choose queries that are 
nost efficient. The following sections indicate guidelines for optimal queries. 
12.3.1 Using EQUAL Rather Than CONTAINING 


\ query is a request for DATATRIEVE to identify all the records that satisfya __ 
pecified condition. A Boolean expression that tests records with the EQUAL (=) 
elational operator is more efficient than a Boolean with CONTAINING (CONT). 
“his rule is most significant if the Boolean expression references a key field: 


TR> PRINT YACHTS WITH BUILDER = "PEARSON" 


TR> PRINT YACHTS WITH BUILDER CONT "PEARSON" 


ilthough both queries yield the same results, the first query is about twice as fast 
s the second one. 


JATATRIEVE gives optimal performance in the first case because the query 
pecifies an exact match for the MANUFACTURER (BUILDER) field, the first 
lementary field of the key field TYPE. DATATRIEVE conducts a fast search 
hrough the index to retrieve the desired records. 
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In the second case, DATATRIEVE must search through the values of BUILDER 
looking for matches with the string following CONT. DATATRIEVE must check 
all substrings of each BUILDER value that are equal in length to the string speci- 
fied in the Boolean. 


To take advantage of the increased efficiency of EQUAL (=), you must specify a 
value that matches the field value exactly. EQUAL (=) is case-sensitive, but 
CONT is not case-sensitive. In the last example, if a record had the value 
“Pearson” for BUILDER, only the second query would find the record. 


To get around the case-sensitivity problem, you can use the DATATRIEVE func- 
tion FN$UPCASE in procedures that store data to ensure that all text fields are 
entered as uppercase. Then you can be sure a search using the EQUAL operator 

will find all the records you want to locate. Otherwise. to use the EQUAL opera- 

tor you must remember the case of each character of a field value. 


12.3.2 Using STARTING WITH Rather Than CONTAINING 


To improve performance. you can sometimes substitute the STARTING WITH 
relational operator for CONTAINING. This operator allows you to find records in 
which the beginning substring of the field value exactly matches the specified 
value expression. If you name a key field in the query, DATATRIEVE is able to 
use a key-based index. Remember that this operator is case-sensitive. 


Of the following two queries, the first query is more efficient because of the keyed 
access. DATATRIEVE does not have to check all possible substrings of each 
BUILDER value: 


DTR> PRINT YACHTS WITH BUILDER STARTING WITH "ALB" 


LENGTH 
OVER 
MANUFACTURER MODEL RIG ALL WEIGHT BEAM PRICE 
ALBERG 37 MK II KETCH 37 20,000 12 $36,951 
ALBIN 79 SLOOP 26 4,200 10 $17,900 
ALBIN BALLAD SLOOP 30 7,276 10 $27,500 
ALBIN VEGA SLOOP 27 5,070 08 $18,600 


DTR> PRINT YACHTS WITH BUILDER CONTAINING "ALB" 


LENGTH 
OVER 
MANUFACTURER MODEL RIG ALL WEIGHT BEAM PRICE 
ALBERG 37 MK II KETCH 37 20,000 12 $36,951 
ALBIN 79 SLOOP 26 4,200 10 $17,900 
ALBIN BALLAD SLOOP 30 7,276 10 $27,500 
ALBIN VEGA — SLOOP 27 5,070 08 $18,600 


DTR> 
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12.3.3. Using Domains Rather Than Collections in an RSE 


DATATRIEVE cannot use indexes to retrieve records from a collection. In gen- 
»ral, then, to get the best performance on key-based queries, use a domain rather 
chan a collection as the source for the RSE. 


[he previous section noted that DATATRIEVE can do a keyed retrieval if you 

ise the STARTING WITH relational operator. The potential gain in performance 
s lost if you form a collection. For example, the following queries use STARTING 
NITH, but DATATRIEVE uses the key-based index only in the first case: 


\TR> PRINT YACHTS WITH BUILDER STARTING WITH "AL" 


ITR> FIND YACHTS; PRINT CURRENT WITH BUILDER STARTING WITH "AL" 


Che first query is substantially faster because DATATRIEVE can do a search 
hrough the index of YACHTS. DATATRIEVE must do an exhaustive search in 
he second case. 


2.3.4 Using the CROSS Clause and Nested FOR Loops 


f you have two domains that share a common field, you can relate their records 
ither with the CROSS clause or with nested FOR loops. For example, the 
(ACHTS and PAYABLES domains share the field TYPE. The following queries 
earch for records from these two sources: | | 


TR> PRINT PAYABLES CROSS YACHTS OVER TYPE 


‘he query has the form “PRINT rse”. The same results can be achieved with 
ested FOR loops. For example: 


TR> FOR A IN PAYABLES 
ON> FOR YACHTS WITH TYPE = A.TYPE 
ON> PRINT A.PAYABLE, BOAT 


‘his query is processed about as fast as the previous example with CROSS. 
\ATATRIEVE is able to use the key-based index to YACHTS. Note these fea- 
ures of the two queries: 


Domains are used rather than collections as record sources. so that 
DATATRIEVE can use its key-based index to the records of YACHTS. 


The OVER clause uses TYPE, a key field only for YACHTS. Because TYPE 
is not a key field in PAYABLES, the queries specify PAYABLES before 
YACHTS. 
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e The YACHTS record stream contains many more records than PAYABLES, 
and is best placed in the second position in each query. 


The next sections explain why these principles affect DATATRIEVE’s | 
performance. 


12.3.5 Choosing Domains or Collections as Record Sources 


To form a query that relates two record sources, you can use either collections or 
domains. Keep in mind that DATATRIEVE can do keyed access only for domains 
and only if the domain is other than the first record source specified. In other 
words, when you use CROSS or nested FOR loops to access two domains and you 
relate those domains through a common key field, DATATRIEVE can use keyed 
access for searching the second domain in the CROSS clause or the domain in the 
second FOR loop. 


If all other conditions are equal, it is better to use a domain name rather than a 
collection name in the second position of a key-based relational query. There is 
one more factor to consider, however: collections are efficient to use if you need to 
refer back to the same group of records in the same DATATRIEVE session. In 
such a case, you may get better performance by forming and naming a collection, 
so that DATATRIEVE does not have to retrieve the same group of records over 
and over again. 


Be aware of this tradeoff when choosing a record source. You gain efficiency with 
a domain when you can use keyed access. On the other hand, you gain efficiency 
with a collection if you reduce the number of times DATATRIEVE must isolate 
the same small group from a large body of records. A collection can also reduce 


the number of records in the record stream and help improve the performance of 
CROSS. 


12.3.6 Choosing the Order of Domain Names in the CROSS Clause 


DATATRIEVE can use a key-based index only for the domain that is specified 
second in the CROSS clause. 


When using the CROSS clause, you can relate two domains that have a common 
field. This field can be specified in the OVER clause or in a Boolean expression 
that is part of the WITH clause. (In the following example, the clause OVER 
TYPE is equivalent to WITH TYPE = TYPE.) If this field is a key for only one of 
the domains, you get a faster response if you specify that domain second in the 

_ CROSS clause: 


DTR> PRINT PAYABLES CROSS YACHTS OVER TYPE 
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ACHTS is listed second because TYPE is a key field only for YACHTS, not for 
AYABLES. If PAYABLES had been listed second, DATATRIEVE’s response 
ould have been substantially slower. The query as shown is more than ten times 
ster than if you list PAYABLES after YACHTS. 


second guideline is to specify the smaller record stream first in the CROSS 
ause: 


R> PRINT BOAT, NAME, BOAT_NAME OF OWNERS CROSS YACHTS OVER TYPE 


1is query is more than twice as fast as the same query with the order of the 
mains reversed. Since the YACHTS record stream is much larger than the 
WNERS record stream, you can save time by allowing DATATRIEVE to use 

e key-based index for YACHTS. DATATRIEVE gets each record in OWNERS, 
relatively small number, and then evaluates the OVER clause by means of the 
dex to YACHTS. 


the reverse order is used, DATATRIEVE gets each record in YACHTS (113 in 
) and then evaluates the OVER clause by means of the index to OWNERS. 

nce there are only 10 OWNERS records, a search through the key-based index 
es not save much time. In the other case, a search through the YACHTS index 
ves a search through all 113 YACHTS records. 


hat is crucial is the number of records in each record stream, not the records in 
e record source. If you are only interested in Alberg’s yachts, it is more efficient 
place YACHTS WITH BUILDER = ”“ALBERG’” in the first position. 
ATATRIEVE evaluates the Boolean using the index to BUILDER and finds one 
cord. Then DATATRIEVE loops through the OWNERS records only once to 

n the two record streams. Though the record source (the YACHTS domain) has 
any records, the record stream based on the source is very small. 


ese principles are important when you use CROSS with more than two 


mains. Assume that you have domains A, B, and C and you relate them in the 
lowing expression: 


[NT A CROSS B OVER X CROSS C OVER Y 


X is a key for B, and Y is a key for C, DATATRIEVE uses both keys in evalu- 
ng the entire expression. DATATRIEVE does not use the keys if X is a key 
ly for A, and Y is a key only for B. 


r example, you could relate the three domains PAYABLES, OWNERS, and 
.CHTS. OWNERS and YACHTS both have TYPE as a key field, so 
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DATATRIEVE is able to use both the index to OWNERS and ins index to 
YACHTS in evaluating the following expression: 


DTR> FOR PAYABLES CROSS OWNERS OVER TYPE CROSS YACHTS OVER TYPE 
DTR> PRINT TYPE, RIG, NAME, BOAT_NAME, PRICE, WHSLE_PRICE 


BOAT WHSLE 

MANUFACTURER MODEL RIG NAME NAME PRICE PRICE 
ALBIN VEGA SLOOP STEVE DELIVERANCE $18,600 $14, 25: 

ALBIN VEGA SLOOP HUGH IMPULSE $18,600 $14, 251 

ISLANDER BAHAMA SLOOP JIM POTEMKIN $6,500 $4,95 

ISLANDER BAHAMA SLOOP ANN POTEMKIN $6,500 $4,951 

ISLANDER BAHAMA SLOOP STEVE POTEMKIN $6,500 $4,951 

ISLANDER BAHAMA SLOOP HARVEY MANANA $6,500 $4,95: 


DTR> 


12.3.7 Order of Domains in Nested FOR Loops 


Nested FOR loops can produce the same results as CROSS, and similar rules 
apply. Include the domain that has the key field in the second or inner FOR loop 
For example: 


DTR> FOR A IN PAYABLES 
CON> FOR YACHTS WITH TYPE = A.TYPE 
CON> PRINT A.ORDR_NUM, BOAT, A. INVOICE_DUE, A.BILL_PAID 


This query is about ten times faster than: 


DTR> FOR A IN YACHTS 
CON> FOR PAYABLES WITH TYPE = A. TYPE 
CON> PRINT ORDR_NUM, A.BOAT, INVOICE_DUE, BILL_PAID 


In the first case. DATATRIEVE knows that the YACHTS bsondet are ordered 
according to TYPE. DATATRIEVE can do a fast search through the index to 

YACHTS for matches on TYPE, before executing the PRINT statement. This 
process is substantially faster. | 


In the second case, however, DATATRIEVE must evaluate the Boolean "WITH 
TYPE = A.TYPE” without the benefit of a key-based index, because TYPE is 
not a key field for PAYABLES. For each record in YACHTS, DATATRIEVE 
must do a search through all of the PAYABLES records to find matches on 
TYPE. 


The same rule holds concerning the relative size of the two record streams. If or 


record stream has many more records than the other and both have the same ki 
field, the larger record stream should be included in the second (inner) FOR loox 
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12.3.8 Nested FOR Loops Followed by a Conditional Statement 


[ry to avoid using nested FOR loops to control the execution of a conditional 
itatement. The following example removes the Boolean expression from the RSE 
ind places it within an IF-THEN statement. It is extremely inefficient: 


ITR> FOR A IN PAYABLES 

‘ON> FOR YACHTS 

‘ON> BEGIN 

'ON> IF TYPE = A.TYPE AND LOA > 40 THEN 
‘ON> PRINT A.PAYABLE, BOAT 

‘ON> END 


JATATRIEVE gets one record from YACHTS and one from PAYABLES., It 
ests for the truth of the condition "TYPE = A.TYPE” AND LOA > 40. Because 
here are 30 records in PAYABLES and 1138 records in YACHTS, DATATRIEVE 
nust go through this procedure 30 X 113 (3390) times. Because DATATRIEVE 

s evaluating the conditions for every record of YACHTS individually, the index 

0 YACHTS based on TYPE is not used. 


“he query is improved when the test is part of the WITH clause of the RSE (or in 
he OVER clause of CROSS). DATATRIEVE does not have to get every record of 
7ACHTS 30 times. For each of the 30 PAYABLES records, DATATRIEVE can 
lo a fast search through the index to YACHTS. 


Vherever possible, you should include conditional tests as Boolean expressions 
rithin the RSE. This effectively limits the number of records that DATATRIEVE 
as to process. For example: 


TR> FOR A IN PAYABLES CROSS YACHTS OVER 
ON> TYPE WITH LOA > 40 
ON> PRINT A.PAYABLE, BOAT 


2.4 Timing Procedures to Improve Efficiency 


‘he recommendations in the previous sections were verified by timing alternative 
rocedures with DATATRIEVE’s timing functions, FN$INIT TIMER and 
‘N$6SHOW TIMER. The first of these functions initializes a timer, and the sec- 
nd calculates the elapsed time. A good comparative measure is the CPU time 
xpended by several alternative procedures that produce the same output. You 
1ay find that the extra effort needed to time procedures may be repaid by 
\ATATRIEVE’s improved performance. 


you will be invoking a procedure frequently and have a choice between two que- 


es, you can time each query to see which one is most efficient. To save CPU 
me, you might include only a subset of the records in your tests. 
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For example, suppose you want to display information on manufacturers who 
make boats with more than one type of rig. This kind of query requires that you 
compare records within the same domain, YACHTS. The first solution, using 
nested FOR loops followed by a conditional, requires DATATRIEVE to search 
and compare the 113 records in YACHTS 113 times. When this inefficient query 
was invoked, the timing functions indicated that it required 50.04 seconds of CPU 
time: 


DTR> SHOW TIME1E 

PROCEDURE TIME1E 

FN_$INIT_TIMER 

FOR A IN YACHTS 

FOR B IN YACHTS 
IF B.BUILDER = A.BUILDER AND B.RIG GT A.RIG 
THEN PRINT B.BUILDER, A.RIG, B.RIG 

FN_$SHOW_TIMER 

END_PROCEDURE 


However, a PRINT statement with a CROSS clause in an RSE achieved the same 
result with the expenditure of only 3.02 seconds of CPU time: 


DTR> SHOW TIME1B 

PROCEDURE TIME1B 

FN_$INIT_TIMER 

PRINT BUILDER, A.RIG, RIG OF A IN YACHTS CROSS 
B IN YACHTS OVER BUILDER WITH A.RIG GT B.RIG 

FN_$SHOW_TIMER 

END_ PROCEDURE 


In these procedures, FNSINIT TIMER starts timing the processing of the 
records and FN$SHOW TIMER displays the elapsed time following completion 
of the processing. 


12.5 DATATRIEVE’s Evaluation of Compound Booleans 


DATATRIEVE sets up a priority when it evaluates compound Boolean expres- 
sions that include key fields. For any domain, the key that is chosen depends on 
three factors: 


¢ Exact or range retrieval 


Exact retrievals use EQUAL or STARTING WITH. 
Bounded range retrievals use BT. 


Range retrievals use GT, GE, LE, or LT. 
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Key is NO DUP or DUP 
Primary or alternate key 


»yed retrieval is performed on Booleans that use the relational operators 
QUAL, STARTING WITH, BEFORE, AFTER, GT, GE, LE, LT, or BT. Table 
-1 indicates DATATRIEVE’s priority in choosing keys. Each line represents a 
mbination of the three attributes noted. The lines of the table are arranged in 
der of diminishing priority. 


ble 12-1: DATATRIEVE’s Priority in Choosing Keys 


Dup/No Dup Type of Key 


NO DUP 






‘ype of Retrieval 









yxact Primary 





Alternate 





Primary 


Alternate 












sounded Range Primary 
Alternate 
Primary 
Alternate 
Primary 
Alternate 


Primary 


Alternate 
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12.6 Summary of Rules 


The following guidelines can help you take advantage of DATATRIEVE’s ; ability 
to use a key-based index to retrieve records: 


e When defining data, make the field most commonly used in queries the pri- 
mary key. If that field does not uniquely determine a record, combine it wit 
another field so the combined fields uniquely determine a record. Allowing 
duplicate values of a primary key slows performance. 


e If you decide to make a group field the primary key, the order of the subord 
nate elementary fields is important. The field most commonly used in querie 
should be the first elementary field listed. Remember that DATATRIEVE 
cannot do keyed access on group field keys that contain numeric items. 


e If there are other fields that will often be used with the primary key in que- 
ries, you can designate them as alternate keys. 


e Use EQUAL (=) instead of CONTAINING (CONT) in the Boolean expres- 
sion of an RSE, when searching for records based on a key field value. 


e When searching for field values beginning with a specified substring, use 
STARTING WITH instead of CONTAINING (CONT). This pute is most 
important when your search is based on a key field. 


DATATRIEVE allows you to relate records from the same domain or two differ- 
ent domains with the CROSS clause or nested FOR loops. When the relationshi 
is based on a key field of at least one of the domains, keep these guidelines in 
mind: 


¢ — If the field is a key for only one of the domains, make sure that domain is n 
specified first in the CROSS clause or included in the first FOR loop. 


¢ Use a domain rather than a collection as the second record source. 
DATATRIEVE cannot do keyed access on collections. A collection, howeve! 
can help performance when it greatly reduces the number of records that 
DATATRIEVE must evaluate in a relational query. In addition, forming an 
naming a collection is useful if you need to use the same subset of records 
several times within a DATATRIEVE session. 


¢ Try not to use a conditional statement following nested FOR loops or follow 
ing a FOR loop that contains an RSE with a CROSS clause. A better | 
approach is to include the conditional test in a Boolean expression within tl 
RSE in the CROSS clause or in the second FOR loop. 


e When relating two or more record streams, do not specify the largest recor: 
stream in the first position of the CROSS clause or in the first FOR loop. 
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Part 5 
DATATRIEVE and the 
VAX Information Architecture 


Using Forms with DATATRIEVE 13 


A form is a terminal screen image used to display and collect information. You 
can use forms to display, modify, and store data managed by DATATRIEVE. 


You can often format a data display more attractively using a form image than 
you can without one. This is particularly true when you need to display records 
longer than the maximum number of characters your terminal screen can accom- 
modate on one line. In addition, nontechnical users are often more comfortable 
entering data through a form interface. They can see all the fields requiring input 
and can judge the size of each field before they begin to enter data. If they are 
modifying or storing data and make errors entering data in a field, they can back 
up to that field and correct the error. 


To use forms with DATATRIEVE, you must have VAX TDMS software or VAX 
FMS software (called simply TDMS and FMS) installed on your system. When 
you install DATATRIEVE, you specify which of these forms products you want to 
use. 


To create a forms application, you need to: 


® Use a forms editor to define a form 


* Insert the form definition in a request library file (TDMS) or form library 
(FMS) 


*» Associate the form definition with a DATATRIEVE domain 
» Make sure that SET FORM is in effect when your application executes 


The following sections discuss each of these steps in greater detail. Because your 
form definition depends, at least partly, on how you plan to use the form, step 3 is 
liscussed first. 
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13.1. Associating a Form with a Domain 


You can use a form to display data from RMS domains, view domains, DBMS 
domains, Rdb domains, and remote domains. 


When working with remote domains, you can use forms to store data into a 
remote domain and to display a selected record or a record from a record stream 
containing no other records. You cannot, however, use forms to display group 
fields from remote domains. 


There are two ways you can associate a form definition with a domain: 


e Use the FORM IS clause within a domain definition to identify a form with 
a particular domain. DATATRIEVE uses that form with any STORE, 
MODIFY, DISPLAY, or PRINT statement that refers to that domain. 


e Use the DISPLAY FORM statement within a DATATRIEVE statement to 
map data to and from specific form and record fields. For example, include 
the DISPLAY FORM statement within a FOR, STORE, or MODIFY 
statement. 


Using either method, you must specify both the name of the form and the file 
specification of the library file containing the form. There are advantages to 

using each method. The FORM IS clause lets you use a form by specifying a sin- 
gle line of syntax in a domain definition. The DISPLAY FORM statement lets 
you specify exactly which fields you want to map between a form and a record and 
lets you associate more than a single form with a domain. 


Note 


DISPLAY FORM is the method you should use if you intend to map 
numeric data between forms and records. Using the DISPLAY FORM 
statement with the FORMAT value expression ensures that decimal 
points and signs are mapped correctly. FORMAT value expressions are 
discussed in the VAX DATATRIEVE Handbook and the chapter on 
value expressions in the VAX DATATRIEVE Reference Manual. 


You can see examples of what form displays look like with some of the sample 
DATATRIEVE domains. To see the examples, make sure your system has a 
version of DATATRIEVE installed with the TDMS or the FMS forms interface 
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d follow these steps: 


Set your default VMS directory to one that contains the data files for the 
YACHTS, SAILBOATS, and FAMILIES domains. If you do not have these 
data files in one of your directories, set your default directory to the system 
directory with the sample data: 


$ SET DEFAULT DTR$LIBRARY 
or 
$ SET DEFAULT SYS$COMMON: [DTR] 


Invoke DATATRIEVE and set your current dictionary to the sample forms 
dictionary: 


DTR> SET DICTIONARY CDD$TOP .DTR$LIB.FORMS 


Make sure that the form setting is in effect for your session. (SET FORM is 
the DATATRIEVE default, but you may have run procedures that include 
the SET NO FORM command.) 


DTR> SET FORM 


Ready the YACHTS, SAILBOATS, or FAMILIES domain. 


Print some records from the domain. Records appear one at a time. Press 
the RETURN key each time you want to display a new record. You return 
to the DTR> prompt once all the records you requested have been dis- 
played. 


Press CTRL/C and then the RETURN key if you want to stop the display 
operation before all the records have been displayed. 


1.1. The FORM IS Clause 


rou include the FORM IS clause in a domain definition, you can have 
.TATRIEVE automatically use the form to display records. 


2 syntax for defining a domain that automatically uses a form is: 


FINE DOMAIN path-name USING record-path-name ON file-spec 
=ORM [IS] form-name [IN] form-library; 
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The following examples show the use of the FORM IS clause in domain defini- 
tions. Note that form-library can be a TDMS request library file or an FMS form 
library. The default file type for TDMS request library files is .RLB; the default 
file type for FMS form libraries is .FLB: 


DEFINE DOMAIN YACHTS_F 
USING YACHT ON YACHT.DAT 
FORM IS YACHTF IN DTRFMS.FLB; 


DEFINE DOMAIN PERSONNEL_F 
USING PERSONNEL_REC ON [MORRISON] PERSON .DAT 
FORM IS PERSON IN [KELLER]FORMSLIB; 


DEFINE DOMAIN REMOTE_FAMILIES USING FAMILIES AT NOVA"LINTER TAD" 
FORM IS FAM IN NOVA"LINTER TAD": :DB3: [LINTER] DTRTDMS ; 


DEFINE DOMAIN SAILBOATS 
OF CDD$TOP .DTR$LIB.DEMO.YACHTS, CDD$TOP. DTRSLIB. DEMO.OWNERS BY 
01 SAILBOAT OCCURS FOR YACHTS. 
03 BOAT FROM YACHTS. 
03 SKIPPERS OCCURS FOR OWNERS WITH TYPE EQ BOAT.TYPE. 
OS NAME FROM OWNERS. 
FORM IS SAIL IN DTR$LIBRARY: FORMS 


DEFINE DOMAIN PART USING PART OF DATABASE PARTS_DB 
FORM IS PARTF IN PARTS.FLB; 


There are some disadvantages to using the FORM IS clause: 
e The field names in the form definition must exactly match the correspondir 
field names in the record definition for the domain. 


¢ You must define a form field for every field in the corresponding record to 
avoid unexpected mapping results. 


e You cannot match form field names to names of REDEFINES fields or to 
query names. 


¢ You may get unexpected results when mapping numeric fields. 


e You cannot prevent the operator from entering data in all the fields on the 
form when you specify the MODIFY or STORE statements, unless the fiel 
were defined as Display Only by the form definer. 


e When the operator presses the RETURN key or ENTER key after a STOR 
or MODIFY operation, data is returned from all the fields on a form, includ 
ing data that may have been previously mapped to a Display Only field. Th: 
may lead to unexpected input. 


¢ You cannot use more than the single form that you specify in the domain 
definition to store or modify data associated with that domain. 


13-4 Using Forms with DATATRIEVE 


» You cannot ready a domain if it contains a FORM IS clause and 
DATATRIEVE has not been installed with a forms package. 


» You may have to take special steps to use the FORM IS clause with applica- 
tions that use FMS and callable DATATRIEVE. See Section 13.4.6.1 for 
more information. 


» You must exercise caution when your application modifies view domains that 
use the FORM IS clause. See Section 13.4.6.3 for more information. 


13.1.2 The DISPLAY FORM Statement 
(he format of the DISPLAY FORM statement is: 


JISPLAY FORM form-name [IN] form-library <--- 1 
[USING statement-1] <---2 
[RETRIEVE [USING] statement-2] <---3 


“orm-library can be a TDMS request library file or an FMS forms library. The 
lefault file type for TDMS request library files is .RLB; the default file type for 
"MS form libraries is .FLB. In the following example, parts corresponding to the 
hree sections of the statement format are labeled for clarity: 


TR> MODIFY YACHTS USING 


ON> ae 
ON> DISPLAY_FORM YACHT_FORM IN FORMSLIB [se 
ON> m5 
ON> USING | 
ON> BEGIN | 
ON> PUT_FORM MANUFACT = MANUFACTURER | 2 
ON> PUT_FORM MODEL = MODEL | 
ON> PUT_FORM PRICE = PRICE | 
ON> END - | 
ON> -+ 
ON> RETRIEVE a 
ON> BEGIN | 3 
ON> PRICE = GET_FORM PRICE | 
ON> END | 
TR> ae 


Tote that. because you specify both record and form field names in the 
)ISPLAY FORM syntax, form and record field names need not match. 


‘he DISPLAY FORM statement gives you four kinds of control not provided by 
ne FORM JIS clause of the domain definition: 
You can associate more than one form definition with a domain. Therefore, 


you can design a variety of forms to fit different purposes. 


The first part of the DISPLAY FORM statement format gives you this con- 
trol. In the example, the DISPLAY FORM statement is embedded in a 
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MODIFY statement and associates the form YACHT FORM with the 
domain YACHTS. -. 8 


e You specify which record field values you want to map to or display on the 
form. . 


Only values from record fields you explicitly assign to form fields are dis- 
played on the form. This allows you to mask sensitive data from certain 
users. The USING clause, number 2 in the format diagram, gives you this 
control. In the example, only the values for the record fields 
MANUFACTURER, MODEL, and PRICE are displayed on their corre- 
sponding form fields. 


If you omit the USING clause of the DISPLAY FORM statement, no record 
field values are displayed on their corresponding form fields. You might want 
to omit the USING clause if you are storing records rather than modifying 
records. 


e You specify the form fields you want to return to the record. 


Only values from form fields explicitly assigned to record fields are returned 
to the record. The RETRIEVE clause, number 3 in the format diagram, 
gives you this control. In the example, only the value in the form field 
PRICE replaces the existing value in the record. 


If you omit the RETRIEVE clause of the DISPLAY FORM statement, no 
form field values entered by the user or sent to the form by DATATRIEVE 
are returned to their corresponding record fields. Omit the RETRIEVE 
clause if you do not want to collect data from the form, and you want to pre- 
vent inadvertent data modification during a display-only operation. 


¢ You specify the format to display, store, and modify numeric fields correctly. 


Using the FORMAT value expression with the DISPLAY FORM statement 
lets you contro] data transfer between numeric record fields and form fields. 
(See Section 13.2.2.1 for information on mapping numeric data types and 
13.4.5 for information on using the FORMAT value expression.) 


The only time you can use the DISPLAY FORM statement without embedding it 
in another statement and without using the optional USING and RETRIEVE 
clauses is when you simply want to display the form itself. In this case, you must 
end the statement with a semicolon (;) to avoid getting an error message. For 
example: . 


DTR> DISPLAY_FORM YACHT IN DTR$LIBRARY : FORMS; 


This type of DISPLAY FORM statement lets you see the form before you use it, 
without exiting from DATATRIEVE. You cannot enter data in the form that is 
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lisplayed. You can use this particular DISPLAY FORM syntax to display a form 
chat is associated with a domain by the FORM IS clause. 


13.2 Defining Forms 


4 form definition contains information that specifies: 


» The screen image of the form. The screen image includes background text 
and the pictures of the fields in which data can be collected and displayed. 


» The length and data type of each field. 
’ A set of attributes for each field. 
» — Video highlights for the form. 


' The name of a help form that the operator can display. 


fou can use the TDMS Form Editor or the FMS Form Editor to define a form. 
“he VAX TDMS Forms Manual explains how to use the Form Definition Utility 
FDU) to create and modify a TDMS form. The Introduction to VAX FMS 
‘xplains how to create and modify an FMS form. 


Sections 13.2.1 to 13.2.6 discuss some considerations you should keep in mind 
vhen creating a form to use with DATATRIEVE. The discussion assumes you are 
amiliar with the process of creating a form definition. If you are unfamiliar with 
he forms product you intend to use with DATATRIEVE, you should create a few 
ample forms before reading these sections. 


3.2.1 Defining Form Field Names 


7ou specify form field names in the Assign phase of your form definition. Any 
ames you specify during the Layout phase of your form definition are back- 
round text. not field names. 


f the form you are creating will be referred to in the FORM IS clause of a domain 
efinition, use the following guidelines when naming form fields: 


If there are any hyphens in the DATATRIEVE field name. they should be 
defined as underscores to FMS because DATATRIEVE converts all hyphens 
to underscores when it converts names to uppercase. 


Form field names can be up to 31 characters long. The form field names 
must match the field names in the DATATRIEVE domain. 


If you convert an FMS Version 1 form definition to FMS Version 2 or TDMS 
and you want to associate the converted form with a DATATRIEVE domain, 
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make sure that the form field names match the record field names. Suppose, 
for example, you have an FMS Version 1 form with the form field MANUFA 
corresponding to the record field MANUFACTURER. If you convert that 
form to FMS Version 2 or TDMS, be sure to edit your new form definition 
and change the name of the form field to MANUFACTURER. 


e When using FMS to define a form, make sure that you define a form field for 
each record field. When using TDMS. make sure that you define a record 
field for each form field. When the record field is a COMPUTED BY field, 
define a counterpart form field and select the Display Only attribute. The 
Display Only attribute prevents users from modifying the field’s data. 


In FMS, if you do not define a form field for each record field, incorrect val- 
ues may be mapped to record fields. 


If the form you are creating will be referred to only in DISPLAY FORM state- 
ments, the DATATRIEVE field names and form field names need not match. In 
addition, you do not have to define a form field for each record field. 


When you are using the DISPLAY FORM statement, you can define a form field 
for a DATATRIEVE variable. You may want to define a form field that maps to a 
variable to use in conditional statements. For example, you could collect an 
employee ID from a form field and return it to a variable. You could then use this 
ID to search a domain and display related employee data on the same form. 
Remember, however, that DATATRIEVE does not process form field values when 
the form user presses TAB to move to another field. The user must press the 
RETURN key before DATATRIEVE can evaluate and process data. In this exam- 
ple, the user would have to enter the employee identification code, ignore the 
remaining fields on the form, and press RETURN. 


If you do not spell a record field name correctly (in DISPLAY FORM assignment 
statements) or do not spell a form field name correctly (either in the form defini- 
tion referred to by the FORM IS clause or in the DISPLAY FORM assignment 
statements). DATATRIEVE ignores the values in those fields. You receive no 
error messages to alert you to possible field name errors. 


13.2.2 Defining Data Type and Length of Form Fields 


When you define a form, you match the form fields with the corresponding record 
fields in two ways: 


e Use a form field picture that describes the same data type as the record defi- 
nition. The field pictures control the type of data a user enters in the form 
field at run time. 


For example, if you define a form field of all 9s; a user cannot move to the 
next form field if they enter anything but a digit in that form field. 
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Though defining a form field picture controls the type of data a user enters, 
it is not the same as defining a data type. For example, you can match an 
alphabetic field picture on a form with a record definition of PIC A, or you 
can match a field picture of 9s on a form with a DATATRIEVE record defini- 
tion of PIC 9s. DATATRIEVE receives data from both TDMS and FMS as 
strings, however, so you cannot completely match form and record definition 
data types. For example, if your record definition defines a field as PIC 9(4) 
USAGE COMP, when you define a form field you can specify the form field 
characters 9999, but you cannot match COMP. 


Make sure your form field has the same length as your record field. 


For example, if the record field is defined as PIC X(25). use 25 Xs for the 
form field. If the form field is longer than the record field, the form user 
might receive a truncation error message and reenter prompt after pressing 
the RETURN key. If the form field is shorter than the record field, existing - 
values for alphanumeric fields are truncated in the form display. A form field 
shorter than the record field might make it impossible for the form user to 
enter a valid value. 


ite that regardless of the form pictures or record data types you assign, 
\TATRIEVE passes all values between forms and records as text strings. This 
ects how it handles numeric field values. as discussed in the following sections 
data types requiring special treatment in form definitions. 


.2.2.1_| Numeric Fields with Decimal Points or Signs -- When matching 
meric record fields that contain signs or decimal points with form field pictures, 
1 may want to follow some of the guidelines in this section. These guidelines 
sume that you are using the DISPLAY FORM statement with the FORMAT 
lue expression. This is the recommended method of handling numeric data 

es. (See Section 13.4.5 for examples of the FORMAT value expression.) 


For numeric record fields that contain an implied decimal point (such as a V 
in the PICTURE clause or a SCALE clause) but not a sign, you can include a 
decimal field-marker character (FMS) or a decimal constant (TDMS) in the 
corresponding place on the form field. 


You do this during the Layout phase of defining your form. 


In the Assign phase of your form definition, you might decide to avoid the 
fixed decimal characteristic. Because values are passed from the form to 
DATATRIEVE as text strings, specifying fixed decimal does not scale 
numeric values for storage. 


_ If you do assign the fixed decimal attribute to a numeric form field, 
perhaps because the form might also be used in applications other than 
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DATATRIEVE, follow these guidelines: 


- Define the associated record field with an implied decimal field, for 
example, PIC 99V99. 


- Define the form field, if it is an FMS form, as 99.99 with fixed decimal 
clear character 0, and zero fill attributes. 


- Define the form field, if it is a TDMS form, as 99.99 with Fixed Decim 
and Zero Fill attributes. 


¢ — If you want a field to have both a decimal point and a sign (either explicit o1 
implicit), in FMS use N instead of 9 for the form field. 


In TDMS, you cannot combine a signed numeric field picture (N)-with the 
Fixed Decimal attribute. To get the effect of a scaled signed number, you cz 
use the N field without the Fixed Decimal attribute in TDMS. TDMS 
assigns a scale factor to fields you describe with an N picture based on the 
field picture. For a field you describe as NNN.NNN in the Layout phase of 
TDMS., it defaults a scale factor of -3. while a field you describe as NN.NN 
assigned a scale factor of -2. 


Table 13-1 provides examples that match form fields to numeric record fields 
when using the DISPLAY FORM statement. Use the FORMAT value expressic 
as illustrated in the example following Table 13-1 and in Section 13.4.5 to ensur 
correct mapping between numeric fields. 


Table 13-1: Matching Form Field Definitions to Numeric Record Fields 


Record Field | Form Field Form Field Attributes 


PIC 999V99 999.99 You can use 9 or N because the data is 
unsigned. 
PIC S9(4)V99 NNNNN.NN An N is required for a signed field. The 


decimal point must agree with the record 
field. 


WORD SCALE -3 NNN.NNN The field must be large enough for the 
maximum value, sign, and decimal places. 


REAL NNNNNNNNN The number of Ns is flexible, but no deci- 
mal point is included because the record 
field contains no implied decimal point. 





LONG SCALE -4 NNNNNNN.NNNN | Similar to the preceding WORD example. 
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Then you use the DISPLAY FORM statement to map numeric fields use the fol- 
wing technique: 


When mapping fields to a form, use the FORMAT VALUE expression with 
an edit string and multiply the data from the record field (as described by the 
edit string) by the scaling factor 


When getting the fields from a form, you divide by the scaling factor before 
storing the data. 


he following procedure illustrates a typical method for mapping numeric fields 
sing a form. 


‘FINE PROCEDURE FORMAT 
tADY TEST_FORMAT WRITE 
GIN 
\R TEST_FORMAT 
GIN 
)ISPLAY_FORM TEST_FORMAT_FORM IN 
"LINTOV] TESTFORM.RLB USING 
BEGIN . 
-PUT_FORM UNSIGNED_FIXED_DEC = - 
FORMAT(100 « UNSIGNED_FIXED_DEC) USING 99999 
PUT_FORM SIGNED_DECIMAL = - 
FORMAT(100 « SIGNED_DECIMAL) USING s999999 
PUT_FORM SCALE_FACTOR_3 = - 
FORMAT(1000 « SCALE_FACTOR_3) USING S99999 
PUT_FORM PLAIN_N = PLAIN_N 
PUT_FORM SCALE_FACTOR_4 = - 
FORMAT(10000 * SCALE_FACTOR_4) USING s99999 
END RETRIEVE USING 
BEGIN 
UNSIGNED_FIXED_DEC = - 
(GET_FORM UNSIGNED_FIXED_DEC/100) 
SIGNED_DECIMAL = - 
(GET_FORM SIGNED_DECIMAL/100) 
SCALE_FACTOR_3 = - 
(GET_FORM SCALE_FACTOR_3/1000) 
PLAIN_N = PLAIN_N 
SCALE_FACTOR_4 = - 
(GET_FORM SCALE_FACTOR_4/1000) 
END 


ID 
ID-PROCEDURE 


3.2.2.2 Usage DATE Fields -- You should define date fields as 11 Xs on your 
rms. DATATRIEVE displays the field in the default date format (DD-MMM- 
YYY). Use 23 Xs to display both date and time. 
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If you want to display the date in other than the default format, you can do so 
with the DISPLAY FORM statement. Define a variable that is computed by a 
format value for the date field and then display the variable rather than the date 
field on the form. In the following example, FIELD2, rather than FIELD1, can be 
mapped to the form: 


Record field: 

03 FIELD1 USAGE DATE. 

Variable: 

03 FIELD2 COMPUTED BY FORMAT(FIELD1) USING MMMBDDBYYYY. 


You might want to add a COMPUTED BY date field such as FIELD2 to the 
record definition if your installation uses the specified date format as the com- 
pany standard. 


When the date field is defined as 11 Xs on your form, the form user can enter on 
of a variety of values and DATATRIEVE stores the date correctly. For example, 
DATATRIEVE stores the date value April 16, 1972 for any of the following 
entries: 


4/16/72 

16 4 1972 
APR 16 1972 
1972/APR 16 


You can also use both the PUT FORM and GET FORM components of the 
DISPLAY FORM statement to map date fields. (See Sections 13.4.3 and 13.4.4). 


13.2.3 Specifying User Entry and Validation Criteria 


DATATRIEVE validation clauses (in the record definition or DATATRIEVE 
statement) are not applied to any field until the form user finishes with a record 
and presses the RETURN key. After the RETURN key is pressed. 
DATATRIEVE looks at the data returned to the record fields and applies the 
record or statement validation clauses. If data in a field is invalid, the user is 
prompted again for valid data for that field. 


Validation associated with the form fields can prevent users from entering incor- 
rect data. Using 9s or Ns for numeric form fields. for instance, ensures that form 
users cannot tab to the next form field if they accidently enter nonnumeric char- 
acters. Even though the Fixed Decimal attribute is not passed to DATATRIEVE 
when field values return from the form, you can specify the attribute in your forr 
definition if you decide it helps the user enter data correctly. 
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hoosing the Fixed Decimal, Right Justify, Left Justify, and Zero Fill attributes 
l affect how the user enters data and therefore can affect what data is returned 
» the record field. 


ssign the Display Only attribute to any fields that the user cannot store into or 
odify. This will prevent the user from entering data in a field. Your 

ISPLAY FORM statement can prevent the user modifications from reaching 

ie stored record. but cannot prevent the user from entering that data in the form 
ald. It is also good practice to prevent form users from entering changes that are 
yt stored. 


Note ———___-________ 


TDMS allows users to assign Field Validators to form fields. 
DATATRIEVE ignores these validators, however, and does not use 
them in any DATATRIEVE/TDMS application. 


.2.4 Defining Multiple Screen Forms and Forms with Scrolled Areas 


aither FMS nor TDMS supports forms that span multiple screens. 
ATATRIEVE does not support forms that contain scrolled regions. 


you modify and store data using the DISPLAY FORM statement, however, 
u can display a series of individual forms to collect and display data within a 
igle procedure. Note that only one form can appear on the screen at a time. 


1.2.9 Using Default Values 


ATATRIEVE’s default value and missing value are displayed on the form fields 
1en you use the FORM IS clause or the PUT FORM component of the 

‘SPLAY FORM statement. The form user generally sees default and missing 
lues only during a store operation. Do not specify default values in your form 
finition. DATATRIEVE does not store these values in the record. 


.2.6 Defining Forms for Domains That Contain Repeating Fields 


mu can define a matching form field for a repeating record field (one that 

sludes an OCCURS clause). For example, a form for the FAMILIES domain 
uld specify KID NAME and AGE as indexed fields. You create an indexed ele- 
»nt to match each occurrence of the record field. 


you are using TDMS, align all occurrences of the repeating fields vertically or 


rizontally in the Layout phase of your form definition. Then. in the Assign 
ase, specify the index attribute for the repeating items. 
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If you are using FMS, follow these steps: — 


1. Inthe Layout phase of your form definition, specify the background text 
and field characters for the first occurrence of the repeating item. 


2. Enter the Assign phase, and specify the attributes you want for the item. 
Type 1 for the index attribute. 


3. Enter the Layout phase again and use the form editor’s cut and paste func- 
tion to create all additional occurrences of the repeating item. FMS auto- 
matically assigns the correct attributes for these additional occurrences. 


Whether you are using TDMS or FMS. make sure you create enough repeating 
form fields to accommodate the maximum number of occurrences defined in the 
record definition. 


13.3 Inserting Forms in Library Files 


After you define a form with the TDMS or FMS Editor, you must insert it in a 
form library. The following two sections describe how to do this for both TDMS 
and FMS forms. 

13.3.1. Inserting Forms in TDMS Library Files 


To insert a TDMS form in a library, use the TDMS Request Definition Utility 
(RDU) to create a request library definition.and build a request library file. 


For example, to use the form definitions YACHT FORM and PERSON in a 
DATATRIEVE application: 
1. Use RDU to define a request library: 


RDU> CREATE LIBRARY DTR_TDMS 


RDUDF N> FORM IS YACHT_FORM; 
RDUDF N> FORM IS PERSON; 
RDUDF N> FILE IS "FORMSLIB"; 
RDUDFN> END DEFINITION; 
RDU> 


2. Build the request library file: 


RDU> BUILD LIBRARY DTR_TDMS 


Information from the form definitions YACHT FORM and PERSON is 
built into the request library file FORMSLIB.RLB. 


3. Use DATATRIEVE to display the form: 


DTR> DISPLAY_FORM YACHT_FORM IN FORMSLIB; 
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ep in mind that a TDMS request library definition and the request library file 
itain other information and instructions, but DATATRIEVE uses only the ref- 
nce to the TDMS form. 


you modify your form definitions in any way, you must rebuild the request 
rary file. To do this, enter RDU and rebuild the request library Beng the same 
JILD LIBRARY command. For example: 


J> BUILD LIBRARY DTR_TDMS 


YMS extracts your latest form definitions from the CDD to include in the 
rary. 


r more information on using RDU to create and modify request libraries, refer 
the VAX TDMS Request Manual. 


r information about converting FMS forms for use with TDMS and 
\TATRIEVE see the discussion of conversion command procedures in the VAX 
IMS Forms Manual. 

.3.2. Inserting Forms in an FMS Library 


u use the FMS/LIBRARY command to perform operations on form files and 
m libraries. After you have defined an FMS form, create a form library for the 
m definition and insert the forms: 


*MS/LIBRARY/CREATE FORMSLIB.FLB YACHTF , PERSON 


1S inserts the form definitions YACHTF and PERSON in the form library 
YRMSLIB.FLB. 


7ou modify the form, replace the modified form in the library. For example: 


*MS/LIBRARY/REPLACE FORMSLIB.FLB PERSON 


r information about converting FMS Version 1 and Version 2 form definitions 
TDMS form definitions, refer to the discussion of the Form Converter Utility 
the VAX FMS Utilities Reference Manual or the discussion of conversion com- 
ind procedures in the VAX TDMS Forms Manual. 


r information about converting FMS Version 1 forms to FMS Version 2 forms, 
er to the VAX FMS Utilities Reference Manual. 
.4_ Using Forms to Display and Collect Data 


ser you define a form and insert the form definition in a form library, you can 
> the form. The following sections explain how to use DATATRIEVE com- 
nds and statements to display, collect, store, and modify data on a form. 
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13.4.1. Enabling and Disabling Form Use 


The command SET [NO] FORM determines whether DATATRIEVE uses a forrr 
If SET FORM is in effect and you ready a domain whose definition includes the 
FORM IS clause, or you use the DISPLAY FORM statement, DATATRIEVE 
opens the form library specified. 


If SET NO FORM is in effect, DATATRIEVE does not open a form library, and 
you cannot use a form. When you are using a domain whose definition includes a 
FORM IS clause. it is sometimes useful to review the contents of many records 
quickly . SET NO FORM allows you to override form display and use regular 
screen display. | 


Note that if you use a DATATRIEVE image installed without a forms package, 
using SET NO FORM does not let you use a domain definition that contains a 
FORM IS clause. You must edit the domain definition to remove the form refer- 
ence or install DATATRIEVE with a forms package. 


The default is SET FORM. 


You can see if SET FORM is in effect by using the SHOW SET UP command. 
You can see which forms are currently loaded by entering SHOW FORMS. To 
release a form loaded with the DISPLAY FORM statement from your workspace 
use the RELEASE form-name command. 


13.4.2 Displaying Data with Forms 


When DATATRIEVE uses forms to display records, only one record at a time is 
displayed on the screen. To proceed to the next record, press the ENTER key or 
the RETURN key. If you want to skip the rest of the records, position the curso 
on a nonnumeric field and press CTRL/C and then the RETURN key. 


The following example shows how to display records from a domain whose defini 
tion includes the FORM IS clause: 


DTR> SET FORM 
DTR> READY YACHTS_FORM 
DTR> PRINT FIRST 10 YACHTS_FORM 


The PRINT statement in this example causes DATATRIEVE to use a form to 
display the first record in YACHTS FORM. DATATRIEVE displays all the field 
you included in your form definition. You can press the RETURN key to display 
the next record. Continue pressing the RETURN key until the tenth record is 
displayed. The next time you press the RETURN key, you get the DTR> 
prompt. 
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f you want to display values for only a few fields, you can use a form with a 
JATATRIEVE view domain or you can use the DISPLAY FORM statement. 
four DISPLAY FORM statement can refer to an entirely different form than the 
me specified in the FORM IS clause. It can also refer to the same form. 


‘or example, suppose you want to display only the type and price of the first ten 
‘achts on the YACHT FORM form. The fields MANUFACTURER, MODEL, 
nd PRICE in YACHTS correspond to the fields MANUFACT, MODEL,and 
*RICE in the YACHT FORM form. Use the following statements: 


TR> FOR FIRST 10 YACHTS 
ON> DISPLAY_FORM YACHT_FORM IN FORMSLIB USING 


ON> BEGIN 

ON> PUT_FORM MANUFACT = MANUFACTURER 
ON> PUT_FORM MODEL = MODEL 

ON> PUT_FORM PRICE = PRICE 

ON> END 


Vith the DISPLAY FORM statement, you can use a number of forms to display 
ata in one domain. For example, suppose you create two forms for YACHTS: 
“"YPE and SPECS. The form TYPE contains the fields MANUFACT and 
AODEL, corresponding to the MANUFACTURER and MODEL fields in 
"ACHTS. The form SPECS contains fields that correspond to the remaining 
"ACHTS fields. 


‘he following example shows how to display each of the first 10 YACHTS records 
n two forms. For each record in the FOR loop, first the TYPE form is displayed 
nd then the SPECS form is displayed: 


OR FIRST 10 YACHTS 
BEGIN 
DISPLAY_FORM TYPE IN FORMSLIB USING 
BEGIN 


PUT_FORM MANUFACT = MANUFACTURER 
PUT_FORM MODEL = MODEL 
END 

DISPLAY_FORM SPECS IN FORMSLIB USING 
BEGIN 
PUT_FORM LENGTH = LOA 
PUT_FORM DISPLACE = DISPLACEMENT 
PUT_FORM RIG = RIG 
PUT_FORM BEAM = BEAM 
PUT_FORM PRICE = PRICE 


END 
END 


lote that when you use the DISPLAY FORM statement. the names of the fields 
1 the domain and the names of the form fields need not match. For example, you 
an design a form, PAY FORM, that contains the fields BADGE, START, and 
AY. These fields correspond to the fields ID, START DATE, and SALARY in 
1e PERSONNEL domain, as illustrated in Figure 13-1. 
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Fieldsin Fields in 
the form the domain 
PAYFRM PERSONNEL 


BADGE <———_—=> ID 
START <=  START_DATE 
PAY ee SALARY 
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Figure 13-1: Corresponding Fields in a Domain and Form 


The next example shows how to display the fields ID, START DATE, and 
SALARY from PERSONNEL using the form PAY FORM: 


DTR> READY PERSONNEL 

DTR> FOR PERSONNEL 

CON> DISPLAY FORM PAY_FORM IN FORMSLIB USING 
CON> BEGIN 


CON> PUT_FORM BADGE = ID 

CON> PUT_FORM START = START_DATE 
CON> PUT_FORM PAY = SALARY 
CON> END 


13.4.3 Storing Data with Forms 


To store records in a domain that is defined to include a FORM IS clause, use the 
STORE statement: 


DTR> READY YACHTS_FORM FOR WRITE 
DTR> STORE YACHTS_FORM 


DATATRIEVE displays the YACHT FORM form, including any default and 
missing values you specify in your record definition. Then DATATRIEVE waits 
for you to enter data. 


While entering data, you can use: 


e The TAB key to move to the next field 

e The BACKSPACE key to move to the previous field 

¢ The right and left arrow keys to move within a field 

e The LINE FEED key to delete the contents of a field 

¢ CTRL/C to stop storing and prevent the current record from being stored 


When you finish entering data, press ENTER or the RETURN key. 
DATATRIEVE attempts to store the record as it appears on the screen. If there 
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e any validation errors, DATATRIEVE displays an error message at the bottom 
the screen and lets you change the field that caused the error. 


te that the FORM IS clause does not give you field-level access in a store 
eration. If you enter a STORE USING statement and the FORM JS clause is 
ur only association of a domain with a form, DATATRIEVE does not display 

e form. If you want a STORE USING statement to display a form, you must 
slude a DISPLAY FORM statement. Interactive data entry on a form displayed 
th DISPLAY FORM is the same as that described for FORM IS. 


you use the DISPLAY FORM statement to store, you must use its RETRIEVE 
use. 


r example, suppose you receive information for YACHTS in parts. The first 
‘ormation you receive is the manufacturer, model, rig, and overall length. You 
unt to store this information and later modify your records to include further 
ta. 


a can define a new form, YACHT FORM1 with the fields VENDOR, MODEL, 
G, and LENGTH. The following procedure shows how to use the form 
\CHT FORM1 to store partial records in the domain YACHTS: 


JCEDURE STORE_YACHTS_1 

ADY YACHTS WRITE 

JRE YACHTS USING © 

DISPLAY_FORM YACHT_FORM1 IN FORMSLIB RETRIEVE USING 


BEGIN 
MANUFACTURER = GET_FORM VENDOR 
MODEL = GET_FORM MODEL ~ 
RIG = GET_FORM RIG 
LOA = GET_FORM LENGTH 
END 


)_ PROCEDURE 


‘ing both the PUT FORM and GET FORM components of the 

SPLAY FORM statement, you can store values in fields without data entry 

m the form user. This is particularly useful when storing values into date fields 
d primary keys. If you specify the Display Only attribute for these fields in your 
‘m definition, you can prevent the form user from overriding the values you 

id to the form. By not selecting the Display Only attribute, you can allow the 
‘m_user to modify such values. 


r example, suppose you create the form PERSON to store data into 
‘(RSONNEL. Figure 13-2 shows the fields in the form PERSON and 
‘responding fields in the domain PERSONNEL. 
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Fields in Fields in 


the form the domain 
PERSON PERSONNEL 
ID <_—_——_——» |) 


STATUS <> EMPLOYEE_STATUS 

NAME <————> _EMPLOYEE_NAME 
\_ FIRST_NAME 
 LAST_NAME 

DEPT <———»> DEPT 

DATE <——————> START_DATE 

SALARY <—————> SALARY 

SUP_ID <-> SUP_ID 
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Figure 13-2: Corresponding Fields in the Form PERSON and the Domain 
PERSONNEL 


The procedure STORE PERSON shows how you can use the form PERSON to 
store PERSONNEL records: 


! Task: store a new employee record. Generate a unique badge 

! number, but allow the user to override it. 

! The default starting date is "TODAY", but the user can override 
! that also. 


PROCEDURE STORE_PERSON 
STORE PERSONNEL USING 
BEGIN 


! Display the ID and DATE on the form. 


DISPLAY_FORM PERSON IN FORMSLIB USING 
BEGIN 
PUT-FORM ID 
PUT<FORM DATE 
END RETRIEVE USING 


1 + MAX ID OF PERSONNEL 
FORMAT "TODAY" USING DD-MMM-YYYY 


! The rest of the fields on the form are empty. 
! Retrieve data the user enters on the form. 


The form PERSON has one field for a name. The domain 
PERSONNEL has fields for FIRST_NAME and LAST_NAME. 
Get the first and last name from the form name string. 
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BEGIN 


DECLARE BLANK_POSITION WORD. 

BLANK_POSITION = FN$STR_LOCATE (GET_FORM NAME, " ") 

FIRST_NAME = FN$STR_EXTRACT (GET_FORM NAME, 1, 
BLANK _POSITION) 


LAST_NAME = FN$STR_EXTRACT (GET_FORM NAME, 
BLANK_POSITION + 1, 50) 

ID = GET_FORM ID 

START_DATE = GET_FORM DATE 


IF (GET_FORM STATUS CONT "T") 
THEN STATUS = "TRAINEE" ELSE STATUS = "EXPERIENCED" 


DEPT = GET_FORM DEPT 
SALARY = GET_FORM SALARY 
SUP _ID = GET_FORM SUP_ID 


END 
‘ND; 


3.4.3.1 Storing Data in Hierarchical Records with Forms -- To store data in 
\ hierarchical record, use the STORE statement and the DISPLAY FORM state- 
nent. This procedure uses the DISPLAY FORM statement to store data in the 
\ierarchical record for the domain FAMILIES: 


IEFINE PROCEDURE STORE_LISTS 
EADY CDD$TOP .DTR$LIB.DEMO.FAMILIES WRITE 


The variable, A, is used to establish context for the 
list field KIDS. : 


TORE A IN FAMILIES USING 


EGIN 
DISPLAY_FORM FAMILY IN DTR$LIBRARY:FORMS RETRIEVE USING 
BEGIN 
MOTHER = GET_FORM MOTHER 
FATHER = GET_FORM FATHER 
NUMBER_KIDS = GET_FORM NUMBER_KIDS 


The MATCH statement transfers the data retrieved 

from the form with the GET_FORM KID_NAME and AGE value 
expressions to the KIDS fields. In other words, each A.KIDS 
field value is transferred from the form to each KIDS record. 


MATCH KIDS, A.KIDS 
BEGIN 
KID_NAME = GET_FORM KID_NAME 
AGE = GET_FORM AGE 
END 
END 
ND 


ND_ PROCEDURE 


ee Chapter 6 for more information about hierarchical records. 
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13.4.4 Modifying Data with Forms 


To modify records in a domain that uses a form, use the MODIFY statement: 


DTR> READY YACHTS_F MODIFY 
DTR> FOR YACHTS_F WITH BUILDER = *."BUILDER" 
DTR> MODIFY 


DATATRIEVE uses the form YACHTF to display the record you specify. You 
can now modify the fields in that record. To move through the form, use the same 
keys you use while storing. 


If there are any validation errors, DATATRIEVE displays the error message at 
the bottom of the screen and lets you change the field that caused the error. If 
you try to modify a key field that is defined with the NO CHANGE attribute, 
however, DATATRIEVE prints an error message and does not modify any fields 
in the record. Because primary key fields are defined NO CHANGE by default, 
you lose all the modifications you make to a record when you try to modify its pri- 
mary key field. If you do not change the primary key field, there is no problem. If 
you do try to modify a primary key field, DATATRIEVE returns an error and 
ignores the other modifications to the record. To avoid the error, you may want to 
define primary key form fields as display only form fields. 


Note that the FORM IS clause does not give you field-level access in a modify 
operation. If you enter a MODIFY USING statement and the FORM IS clause is 
your only association of a domain with a form, DATATRIEVE does not display 
the form. If you want to use a MODIFY USING statement to display a form, you 
must include a DISPLAY FORM statement. 


You can include the DISPLAY FORM statement within a MODIFY USING 
statement to modify data in a domain, whether or not a form is already assigned 
to the domain with the FORM IS clause. 


If you use DISPLAY FORM to modify, you include all sections of the statement. 
The PUT FORM statements display the data users are to modify, and the 
GET FORM value expressions store their changes. 


In Section 13.4.3, the procedure STORE YACHTS 1 created records with data 
for the fields MANUFACTURER, MODEL, RIG, and LENGTH OVER ALL. 
Suppose you now have data for the rest of the fields and want to update the 
records you stored. You do not want to modify the data already entered; you want 
to enter values only for the fields DISPLACEMENT, BEAM, AND PRICE. 
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One way to perform this task is to create a new form, YACHT FORM2. This 
form contains fields that correspond to all the fields in YACHTS, as illustrated in 
Figure 13-3. 


Fields in Fields in 
the form the domain 
YFRM2 YACHTS 


VANUFA <————> MANUFACTURER 
VODEL _—_——————> MODEL Display 
2IG eS AiG ; 


-ENGTH <> _LENGTH_OVER_ALL 


ISPLA —_—————-_ DISPLACEMENT 
3EAM <> _ BEAM Modify 
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‘igure 13-3: Corresponding Fields in YACHT FORM2 and YACHTS 


Vhen creating the form YACHT FORM2, you can assign the Display Only 
ittribute to the first four fields. In this way, you allow the form user to enter data 
mly for the last three fields. 


‘he procedure STORE YACHTS 2 shows how to modify data on a form: 


ROCEDURE STORE_YACHTS_2 
EADY YACHTS MODIFY 


Modify only YACHTS that are missing data. 


OR YACHTS WITH DISPLACEMENT = 0 
ODIFY USING 
BEGIN 


Use the form YACHT_FORM2 to display entire records. 
DISPLAY_FORM YACHT_FORM2 IN FORMSLIB USING. 


Display the fields for which data has been entered. 
These fields are defined as Display Only to TDMS or FMS. 
The user cannot enter data in them. 

(If you do not define these fields as Display Only, the 
user can change the form fields. However, DATATRIEVE 
ignores the changes.) 


(continued on next page) 
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BEGIN 


PUT_FORM MANUFACT = MANUFACTURER 
PUT_FORM MODEL = MODEL 
PUT_FORM RIG = RIG 

PUT_FORM LENGTH = LOA 


END RETRIEVE USING 


! Get new data from the form. 


BEGIN 
DISPLACEMENT = GET_FORM DISPLACE 
BEAM = GET_FORM BEAM 
PRICE = GET_FORM PRICE 
END 
END 
END_PROCEDURE 


13.4.4.1 Modifying Data in Hierarchical Records with Forms -- To modify 
data in a hierarchical record, use the MODIFY statement and the 
DISPLAY FORM statement. This procedure uses the DISPLAY FORM state- 
ment to modify data in the hierarchical record domain FAMILIES: 


DEFINE PROCEDURE MODIFY_LIST 

READY CDD$TOP.DTR$LIB.DEMO.FAMILIES WRITE 

FIND ALL FAMILIES WITH FATHER CONT *."father’s name" 
FOR CURRENT 


BEGIN 
MODIFY USING DISPLAY_FORM FAMILY IN DTR$LIBRARY: FORMS USING 
BEGIN 
PUT_FORM FATHER = FATHER 
PUT_FORM MOTHER = MOTHER 


PUT_FORM NUMBER_KIDS = NUMBER_KIDS 


! 
! The FOR loop establishes context for the KIDS field. 
! 


FOR KIDS 
BEGIN 
PUT_FORM KID_NAME = KID_NAME 
PUT_FORM AGE = AGE 
END 
END RETRIEVE USING 
BEGIN 
FATHER = GET_FORM FATHER 
MOTHER = GET_FORM MOTHER 


NUMBER_KIDS = GET_FORM NUMBER_KIDS 


(continued on next page) 
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The FOR loop establishes the context for retrieving 
modified values from each occurrence of KIDS that 
satisfies the RSE and for storing those values in 
the KIDS record. 


FOR KIDS MODIFY USING 
BEGIN 


KID_NAME 
AGE 


GET_FORM KID_NAME — 
GET_FORM AGE 


END 
END 
ID 
ID-PROCEDURE 


ee Chapter 6 for more information about hierarchical records. 


3.4.5 Handling Numeric Data 


[any numeric fields are stored with a fractional component and a sign. These 
elds may include a PICTURE string that explicitly specifies a sign and decimal 
dint, for example, PIC S999V99. However. numeric values for some fields 
iclude a sign and fractional component in storage, even though there is no pic- 
ire string to alert you to this fact. Some examples are record fields defined as 
SAGE REAL, USAGE WORD SCALE IS -2. or USAGE LONG SCALE IS -3. 
ection 13.2.2.1 explains how to define form fields that can contain both a sign 
id a decimal point. 


you use the FORM IS clause to transfer data to and from record fields that 
clude a fraction and a sign in storage, results can be undesirable. As a general 
tle, never include the FORM IS clause in a domain definition when its record 
*finition includes these numeric fields. Always use the DISPLAY FORM state- — 
ent to store, display, and modify such numeric fields. When you use the 
ISPLAY FORM statement. you can assume control of the format and scale of 

ie text string passed between the record field and the form field. 


1e following example illustrates how you handle numeric data that includes a 
cimal point and a sign. The CB BALANCE field in the CHECKBOOK domain 
defined as PIC S999V99. The associated BALANCE field on the CHECKS 
rm is defined as NNNN.NN. 


1e DISPLAY FORM statement transfers the value from the record field as a 
10le number and uses a FORMAT value expression to specify the text string as 
should appear on the form field. The edit string in the example includes a minus 
zn (-) as a numeric insertion character so that only negative values are displayed 
th a sign. As an alternative, you can use a plus sign (+) if you want positive as 
21] as negative values displayed with signs. 


>cause the value CB BALANCE is stored with two decimal digits. the 

JT FORM assignment statement must multiply the field value by 100 before 
ansferring it to the form field. The Assignment statement in the RETRIEVE 
ction divides the whole number value from the form field by 100 before storing 
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it in the record field. Note that a FORMAT expression edit string is not neces- 
sary when the form field value returns to the record field: 


DTR> MODIFY CHECKBOOK USING 
DTR> DISPLAY_FORM CHECKS IN FORMSLIB USING 
CON> PUT_FORM BALANCE = 


CON> FORMAT (100 * CB_BALANCE) USING 
CON> -99999 RETRIEVE USING 
CON> CB_BALANCE = (GET_FORM BALANCE) / 10 


You must multiply and divide values by the appropriate power of 10 for the recor: 
field definition. The example multiplies and divides values by 100 because the 
record field stores two decimal places. If, for example, the record field you are | 
handling includes a SCALE IS -3 clause, you multiply and divide values by 1000. 


Form fields that include a decimal point and are defined as 9s require the same 
treatment in a DISPLAY FORM statement. Because such fields cannot include ¢ 
sign character, however, you omit the plus (+) or minus (-) character from the 
edit string in the FORMAT value expression. 


13.4.6 Restrictions on ‘Using Forms 


The following sections describe restrictions on using DATATRIEVE with forms. 
They also provide examples of alternatives to these restricted uses of forms. 


13.4.6.1 DATATRIEVE and FMS -- When you use the DISPLAY FORM state- 
ment with FMS forms, DATATRIEVE passes a default field descriptor of 255 
characters. If you try to concatenate fields from an FMS form, you get unex- 
pected results. You can explicitly specify the description of a form field using the 
FORMAT value expression. Include an edit string in the USING clause of the 
FORMAT value expression so that DATATRIEVE does not use the 255- 
character default for an FMS form field. 


The following example specifies field lengths for the fields MANUFACTURER 
and MODEL using FORMAT value expressions: 


DECLARE FLD PIC X(30). 
DISPLAY_FORM YACHT_FORM IN FORMSLIB; 
BEGIN 
PUT_FORM MANUFACTURER = MANUFACTURER 
PUT_FORM MODEL = MODEL 
END RETRIEVE USING 
FLD = FORMAT (GET_FORM MANUFACTURER) USING X(20)| - 
FORMAT (GET_FORM MODEL) USING X(6); 
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Vhen DATATRIEVE concatenates the MANUFACTURER and MODEL fields, 
,uses 20 characters for MANUFACTURER and 6 characters for MODEL 
istead of 255 characters for each field. 


n additional restriction concerns the use of FMS forms with the DATATRIEVE 
all Interface. If you have an application program that displays FMS forms and 
iso calls upon the DATATRIEVE Call Interface to display forms using the 

ORM IS clause in a domain definition, you must save and restore the FMS ter- 
tinal control areas after each call to DATATRIEVE. This restriction applies only 
» use of the DATATRIEVE Call Interface with domains using the FORM IS 


ause. You can avoid the restriction by using DISPLAY FORM instead of 
ORM IS. 


ee the Introduction to VAX FMS for more information about FMS terminal con- 
ol areas. See the FMS documentation for more information about the restriction 
1 using the DATATRIEVE Call Interface. 


3.4.6.2 DATATRIEVE Command Files and Forms Products -- This restriction 
1d its workaround apply only to V2 and later of FMS and V1 and later of TDMS. 


ATATRIEVE uses SYS$INPUT to get its commands from VMS command 
es. Both FMS and TDMS also use SYS$SINPUT to get terminal input. 
1erefore, you cannot use both DATATRIEVE and a forms product in the same 
mmand file unless you set up that file using the following steps: 


The default interactive assignment for SYS$INPUT is your terminal. When 
you run a command file, SYS$INPUT is the command file itself. Therefore, 
your command file must assign SYS$INPUT to SYS6COMMAND (the 
default device name of your terminal) so that the forms product can get input 


from the terminal. That assignment must precede the invocation of 
DATATRIEVE: 


$ ASSIGN/USER_MODE SYS$COMMAND SYS$INPUT 


Then you must include all the DATATRIEVE commands and statements in 
a procedure that is invoked by the command file. 


te resulting command file takes this form: 


ASSIGN/USER_MODE SYS$COMMAND SYS$INPUT 
DTR EXECUTE procedure-name 
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13.4.6.3 Modifying Data Using View Domains and FORM IS -- You must be 
very careful when modifying records in a view based on more than one domain. 

The restriction documented here applies to modifying a field in a view when the 
modified field is the basis for selecting records from another domain. Although 

this restriction applies to views, it is included here to illustrate how the use of a 
form with views can mask modification errors. 


You unintentionally modify data if you try to modify fields when all of the follow- 
ing conditions are true: 


¢ You modify records in a view domain that uses FORM IS. 


e The view selects records from another domain based on the value of a field i 
the view. 


e You modify the field that forms the basis for selecting records from the sec- 
ond domain. 


The following example shows what happens when you try to modify fields that 
refer to other domains in a view using a form. The sample view domain 
SAILBOATS has been edited to create the example. . 


The view domain containing a FORM IS clause: 


DOMAIN SAILBOATS 
OF YACHTS, OWNERS BY 
01 SAILBOAT OCCURS FOR YACHTS. 
03 BOAT FROM YACHTS. 
03 SKIPPERS OCCURS FOR OWNERS WITH BUILDER EQ BOAT.BUILDER. 
OS NAME FROM OWNERS. 
FORM IS SAIL IN DTR$LIBRARY: FORMS 


SAILBOATS refers to the OWNERS domain based on the value for BUILDER. 


Here are the OWNERS records before the modification: 


DTR> READY OWNERS 
DTR> PRINT OWNERS 


OWNER 

NAME BOAT NAME BUILDER MODEL 
SHERM MILLENNIUM FALCON ALBERG 35 
STEVE DELIVERANCE ALBIN VEGA 


HUGH IMPULSE ALBIN VEGA 
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fou modify SAILBOATS: 


TR> FOR FIRST 1 SAILBOATS WITH ANY SKIPPERS MODIFY 

JATATRIEVE displays the first record that meets the criterion WITH 
$;UILDER EQ BOAT.BUILDER on the form, and you modify the record to 
iclude a new value for BUILDER: 


YACHT SPECIFICATION DATA 


Builder: ALBERG ! Changed to ALBIN Model: 37 MK ITI 
Length: 37 - Beam: 12 Disp: 20000 
Rig: KETCH PRICE: 36951 


Owners: SHERM 


IATATRIEVE updates all the fields on a form when a you press ENTER or 
ETURN to complete data entry. Because you changed ALBERG to ALBIN, the 
wner name from the updated record appears in the next record for which there is 
BUILDER named ALBIN. 


HERM now replaces STEVE in that OWNERS record. 


'R> PRINT OWNERS 


INER 

iME BOAT NAME BUILDER MODEL 

[IERM MILLENNIUM FALCON ALBERG 35 

IERM DELIVERANCE ALBIN VEGA 
IMPULSE ALBIN VEGA 


‘M EGRET C&C . CORVETTE 


3.4.6.4 Special Graphics Characters in Forms -- When you design a form 
‘ing characters from the VT100 Special Graphics set, the characters might not 
ittomatically work from one form invocation to the next. If this problem occurs, 
ess CTRL/W to repaint the form. 
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ee 


Using DATATRIEVE with DBMS 14 


his chapter describes the commands, statements, and clauses that let you use 
AX DATATRIEVE with VAX DBMS databases. 


you already use DATATRIEVE, you can skip the section that deals with 
rming a DATATRIEVE query statement. This chapter discusses basic DBMS 
mcepts. For more information about DBMS concepts, read the VAX DBMS 
troduction to Database Administration and VAX DBMS Introduction to Data 
fanipulation. 


you use DBMS but are not familiar with DATATRIEVE, you can supplement 
iis chapter by reading the chapter on writing record selection expressions in this 
anual and Chapter 1 of the VAX DATATRIEVE Handbook on basic 
ATATRIEVE concepts. You can also read the chapter in the VAX 
ATATRIEVE Guide To Writing Reports on creating reports from a DBMS 
itabase. 


| this chapter, you learn to: 


‘Create a database definition in DATATRIEVE that represents a DBMS 
database 


Access the DBMS database either by readying it directly or by defining 
domains for each DBMS record and readying the domains 


Locate DBMS records in a variety of ways 
Print whole records or parts of records 
Store and modify records 

Erase records 


Connect, reconnect, and disconnect records from sets 
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e Define and access view domains and hierarchical DBMS records 


e Create procedures and indirect command files that access DBMS records 
and sets 


This chapter uses examples in the PARTS sample database included with the 
DATATRIEVE User Environment Test Package (UETP) and installed on your 
system. The following command sets the CDD default to the directory that con- 
tains the database domain definitions used in this chapter: 


DTR > SET DICTIONARY CDD$TOP .DTR$LIB.DEMO.DBMS 


14.1 Advantages of Using DATATRIEVE 


Although VAX DBMS has its own interactive query language to access DBMS 
data, you may prefer to use DATATRIEVE. By using DATATRIEVE syntax with 
a few special DBMS extensions, you can: 


e Find and manipulate groups of records 
¢ Modify, update, and erase DBMS data 
e Create reports 

e Plot graphs 


® Relate data stored in RMS files and Rdb databases with data stored in 
DBMS databases 


¢ Use FMS or TDMS forms to access and change DBMS data 


Using DATATRIEVE, you can access individual records, groups of records, and 
records related according to information in a DBMS set. A setis a DBMS data 
structure that establishes a relationship among records. 


For example, in the sample PARTS database, there is a set named 
CONSISTS OF. This set, illustrated in Figure 14-1, contains pointers that iden- 
tify which employees (in the EMPLOYEES domain) work for which divisions (in 
the DIVISIONS domain). 


A single record in the DIVISIONS domain is called a single record occurrence. A 
single record occurrence is the data of a single record in the database. For exam- 
ple, the SOFTWARE division is a single record occurrence. 


This single record occurrence is related to another set of records by the informa- 
tion in a single set occurrence of the set. A single set occurrence contains one 
owner record occurrence and zero or more member record occurrences. 
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DIVISIONS 


CONSISTS_OF —_————"">>>>~- Set name 







EMPLOYEES 
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igure 14-1: DBMS Set CONSISTS OF 


1a DBMS database, relationships between records are always described in sets. 
or example, the single owner record occurrence of the SOFTWARE division is 
mnected to employee records by the information in a single occurrence of the set 
ONSISTS OF. Figure 14-2 shows this relationship. 


SOFTWARE 


SONSISTS_OF — Single set occurrence 






HUTCHINGS 
IACOBONE 
PASCAL 
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gure 14-2: Single Set Occurrence 


he information that employees HUTCHINGS, IACOBONE, and PASCAL work 
r the SOFTWARE division is described in the single set occurrence of the 
ONSISTS OF set. 


| addition to manipulating data, a big advantage of using DATATRIEVE with 
BMS data is that you can easily format that data by using DATATRIEVE 
‘aphics and Report Writer. See the VAX DATATRIEVE Guide to Graphics and 
AX DATATRIEVE Guide to Writing Reports for information on using these 
atures of DATATRIEVE. DATATRIEVE provides specialized syntax to work 
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with DBMS records and these set relationships: 


° Two define commands (DEFINE DATABASE and extensions to DEFINE 
DOMAIN) 


e  Anextension to the READY command (READY database-path-name) 
¢ Two SHOW commands (SHOW SETS and SHOW DATABASES) 


e Three clauses that extend the record selection expression and refer to 
records as participants in sets (MEMBER. OWNER, and WITHIN) 


e An extension to the STORE statement (CURRENCY clause) 


® Three statements to work with sets (CONNECT, DISCONNECT, and 
RECONNECT) 


° Two database commands (COMMIT and ROLLBACK) 


14.2 Defining a Database: The DEFINE DATABASE Command 


To access DBMS records and sets, you must define the DBMS database in 
DATATRIEVE terms. Using the DEFINE DATABASE command, you create a 
DATATRIEVE “database instance” for the DBMS database. 


The DEFINE DATABASE command: 


e Defines a pointer to the DBMS database and gives the database a unique 
DATATRIEVE name 


® Identifies the DBMS schema, subschema, and root file you want to access 
and associates it with the DATATRIEVE database name 


° Stores the new database definition in the CDD 


You must specify the name of a subschema, its schema, and the associated 
database root file. in that order. 


The following example defines a database instance. The CDD path name of the 
schema is CDD$TOP.DTR$LIB.DEMO.DBMS.PARTS. The name of the 
subschema is PART, and the root file is DTR5LIBRARY:DTRPARTDB.ROO. 


DTR> DEFINE DATABASE PARTS_DB 
DFN> USING SUBSCHEMA PART 


DFN> OF SCHEMA CDD$TOP .DTR$LIB.DEMO.DBMS.PARTS 
DFN> ON DTR$LIBRARY : DTRPARTDB . ROO; 
DTR> 
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he format for this command is: 


EFINE DATABASE dbms-database-path ee (1) 
[USING] [SUBSCHEMA] subschema-name =e « -------- (2) 
[OF] [SCHEMA] schema-path-name < n-n-2-- (3) 
ON root-file-spec; a (4) 


|. The dbms-database-path is the DATATRIEVE name you use for your 
database instance. 


?, The subschema-name is the DBMS name of the definition that defines 
records and their relationship to each other. The DBMS user creates the 
subschema definition when the DBMS database is created. It describes 
just that portion of a DBMS database or schema needed by a particular 
application. 


}. The schema-path-name is the DBMS name of the definition that contains all 
area, record, data item, and interrecord relationship (set) definitions. It 
describes how relationships are established and discontinued in a database, 
or how a record becomes a member of a set and is taken out of a set. It also 
describes set order. 


The DBMS user creates it in a file using the DBMS Data Definition 
Language (DDL). When the DBMS user compiles this definition using the 
DDL/COMPILE command, the definition is loaded into the CDD. A subse- 
quent DBO/CREATE command issued by a DBMS user from DCL level 
creates the database. The DBMS schema can be referenced by more than 
one database instance. 


The root-file-spec is the name of the database root file. A DBMS root file 
contains all the information needed by DBMS to access the schema, 
subschema, and the data files at run time. The DBMS user creates the root 
file. 


1.3 Accessing the Database 


‘ter you define a database, you can access it in one of two ways: 
Ready it directly with the READY database-path-name command 


Define domains for each record in the database with the DEFINE DOMAIN 
command and then ready each domain 
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Using the first method, you can ready all the records associated with that 
database using a single READY command. The advantage of using this method is 
that you need not define a domain for each record in the DBMS database. The 
syntax is simpler and readying a database may be faster than readying the sepa- 
rate domains. 


Using the second method, in addition to defining the database, you need to define 
, adomain for each DBMS record. The advantage of using this method is that you 
can use view domains, and you can associate a form definition with a DBMS 
record in the domain definition. 


The next sections discuss these two methods. 


14.3.1 Readying an Entire Database Directly 


When you ready a database directly, you can access all the data from: 


e All or selected DBMS records associated with that database in the DBMS 
subschema definition 


¢ The sets in which those records participate 


For example, if you ready PARTS DB, you can access all the records in the 
PART subschema definition. When you do a SHOW READY command, you see 
all the records made available by the READY command. 


DTR> READY PARTS_DB 


DTR> SHOW READY 
Ready sources: 
CLASS: Record, DBMS, shared read 
<CDD$TOP . DTR$LIB.DEMO.DBMS.PARTS_DB; 1> 
COMPONENT: Record, DBMS, shared read 
<CDD$TOP . DTR$LIB.DEMO.DBMS .PARTS_DB; 1> 
DIVISION: Record, DBMS, shared read 
<CDD$TOP . DTR$LIB . DEMO .DBMS .PARTS_DB; 1> 
EMPLOYEE: Record, DBMS, shared read 
<CDD$TOP .DTR$LIB.DEMO.DBMS.PARTS_DB; i> 
PART: Record, DBMS, shared read 
<CDD$TOP . DTIR$LIB .DEMO.DBMS .PARTS_DB; 1> 
QUOTE: Record, DBMS, shared read 
<CDD$TOP .DTR$LIB.DEMO.DBMS.PARTS_DB; 1> 
SUPPLY: Record, DBMS, shared read 
<CDD$TOP . DTR$LIB.DEMO.DBMS .PARTS_DB; 1> 
VENDOR: Record, DBMS, shared read 
<CDD$TOP . DTR$LIB .DEMO.DBMS .PARTS_DB; 1> 
No loaded tables. 


DTR> 
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‘he format for the READY command for databases is: 


iEADY database-path-name 


[SNAPSHOT] 
PROTECTED READ 
SHARED WRITE 
EXCLUSIVE MODIFY 

EXTEND 


USING rdb-relation-name [AS alias] 
dbms-record-name 


[SNAPSHOT] 
Est] 
PROTECTED READ 
SHARED WRITE 
EXCLUSIVE MODIFY 
EXTEND 


The database-path-name is the DATATRIEVE name you defined for your 
database instance. 


», The access options (PROTECTED, SHARED, and EXCLUSIVE) and the 
access modes (READ, WRITE, MODIFY, and EXTEND) are discussed in 
Section 14.3.3. SHARED READ is the default access for DBMS 
databases. 


. The USING clause allows you to limit database access to specified DBMS 
records. If you omit the USING clause of the READY command, all records 
in the database are readied. 


The dbms-record-name is the name used by the DBMS user to define 
DBMS records in the subschema definition. 


The alias name is a name you use to refer to the DBMS record specified. If 
you include an alias, you must use it in all the DATATRIEVE statements 
and commands that refer to the DBMS record. 


ote that you can ready selected DBMS records in the database. You need not 
ady them all. You can specify access options for each record, as well as options 
r the entire database. 
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For example: 


pote READY PARTS_DB USING EMPLOYEE READ, DIVISION WRITE 
> ‘ 
DTR> SHOW READY 
Ready sources: 
DIVISION: Record, DBMS, shared write 
<CDD$TOP . DTR$LIB.DEMO.DBMS.PARTS_DB; 1> 
EMPLOYEE: Record, DBMS, shared read 
<CDD$TOP .DTR$LIB.DEMO.DBMS.PARTS_DB; 1> 
No loaded tables. 


DTR> 


- This READY command provides access to all the data from: 


° The records associated with those domains (EMPLOYEE and DIVISION 
records) 


e The sets in which those records participate (MANAGES, CONSISTS OF. 
ALL EMPLOYEES) 


14.3.2 Defining and Readying DBMS Domains 


You can also access DBMS data by defining a domain for each DBMS record you 
require. DATATRIEVE automatically maps database records to these domains. 


In the following example, you: 


¢ Define a DBMS domain (PART S) 
e Identify the associated DBMS record type (PART) 
¢ Identify the DATATRIEVE instance (PARTS DB) of the DBMS database 


DTR> DEFINE DOMAIN PART_S USING 
CON> PART 

CON> OF DATABASE PARTS_DB; 
DTR> 


The format for the DEFINE DOMAIN command for DBMS domains is: 


DEFINE DOMAIN domain-path-name — oo) 
[USING] record-path-name <------ (2) 
[OF] [DATABASE] database-path-name (eeecee (3) 


[FORM [IS] form-name [IN] form-library]; < wonsee (4) 
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1. The domain-path-name is the name you assign the DBMS domain you are 
creating. This DBMS domain is a DATATRIEVE structure that points to 
the DBMS record type. To avoid confusion, this name should not be the 
same as the DBMS record name and cannot be the same as the DBMS 
database name. 


2. The record-path-name is the name of a record type contained in the 
subschema of the specified database. You must define a domain and specify ° 
a single DBMS record name for each record type in the DBMS database 
you want to access. 


3. The database-path-name is the database instance you defined in the 
DATATRIEVE DEFINE DATABASE command. 


4. The form-name is the name of a form associated with the DBMS domain. 
The form-library is the file specification of a form library. 


or the full syntax of this command, see the VAX DATATRIEVE Reference 
fanual. . 


he following examples define domains for all the records (in addition to the 
ART record defined above) in the DBMS PARTS database. The domains are 
LASSES, COMPONENTS, DIVISIONS. EMPLOYEES, QUOTES, 
UPPLIES, VENDORS. 


ote that you establish a domain definition for each record type you want to 
cess in the PARTS DB database. (Blank lines separate the definitions for 
arity.) 


[R> DEFINE DOMAIN CLASSES USING 

)N> CLASS OF DATABASE PARTS_DB; 
[R> 

[R> DEFINE DOMAIN QUOTES USING 

)N> PR_QUOTE OF DATABASE PARTS_DB; . 
[R> ; 

[R> DEFINE DOMAIN SUPPLIES USING 

)N> SUPPLY OF DATABASE PARTS_DB; 
'R> 

'R> DEFINE DOMAIN VENDORS USING 

)N> VENDOR OF DATABASE PARTS_DB; 
"R> =: re 

"R> DEFINE DOMAIN EMPLOYEES USING 
\N> EMPLOYEE OF DATABASE PARTS_DB; 


"R> DEFINE DOMAIN COMPONENTS USING 
N> COMPONENT OF DATABASE PARTS_DB; 


"R> DEFINE DOMAIN DIVISIONS USING 
IN> DIVISION OF DATABASE PARTS_DB; — 


Using DATATRIEVE with DBMS _ 14-9 


As with the database or DATATRIEVE RMS domains, you must ready DBMS 
domains before you can access data from those domains. When you use the 
READY command on a DBMS domain, you get access not only to a record type, 
but to the sets in which the record type participates. 


For example, the following command readies the domains EMPLOYEES and 
DIVISIONS: 


DTR> READY EMPLOYEES, DIVISIONS 


It provides access to all the data from: 


e The records associated with those domains (EMPLOYEE and DIVISION 
records) 


¢ The sets in which those records participate (MANAGES, CONSISTS OF, 
ALL EMPLOYEES) 


The format for the READY command is: 
READY domain-path-name [AT node-spec] [AS alias-1] 


PROTECTED READ 
SHARED WRITE Aer | 
EXCLUSIVE MODIFY 
EXTEND 
[SNAPSHOT] 
Note 


You must ready all participants in a set (both owner and member 
domains) to access data identified by that set. The descripton of all of 
the arguments to the READY command is in the VAX DATATRIEVE 
Reference Manual. 


14.3.3 Results of the READY Command 


When you ready a DBMS database, DBMS record, or a DBMS domain. all the 
realms in which a DBMS record participates are automatically readied. A realm i 
one or more schema areas and is defined in a subschema. A realm lets you restric 
or grant access to sections of a database. 


Ask your system administrator for a listing of the realms for the subschema you 
are using. The realms are ultimately associated with storage areas, DBMS units 
contained in single files. It is actually these files that are opened, through a 
READY command that readies at least one of the domains in that file. 
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(ou can ready a database or a domain as SHARED, PROTECTED, or 
"XCLUSIVE. The READY options you choose determine the level of VAX 
JBMS locking. Locking affects both you and other active users. You can also 
pecify how you access the domains or records for READ, WRITE, MODIFY, or 
UXTEND access. 


jee the VAX DATATRIEVE Reference Manual and the VAX DBMS Database 
Jesign Guide for information on access options and modes. 


Vhen used with DBMS domains, DBMS records or the entire DBMS database, 
he READY command has these effects: 


Each specified domain or DBMS record is readied with the requested 
access. | 


The default access mode is SHARED READ. If you do not specify 
EXCLUSIVE or PROTECTED access, DATATRIEVE always readies for 
SHARED access. 


When you ready more than a single domain or DBMS record in the realm: 


- If you enter a SHOW READY command, you see the DBMS records 
and domains with the access option and mode you specified in the 
READY command. For example: 


DTR> READY PARTS_DB USING SUPPLY, VENDOR EXCLUSIVE WRITE 


DTR> SHOW READY 
Ready sources: : 
SUPPLY: Record, DBMS, shared read 
<CDD$TOP . DTR$LIB. DEMO.DBMS. eee DB; > 
VENDOR: Record, DBMS, exclusive wri 
<CDD$TOP . DTR$LIB. DEMO.DBMS. PARTS _DB;1> 


- However, other users’ access to those records or domains is limited by 
the most restrictive access you specify in a READY command. This 
restrictive access applies until you ready the DBMS domain or record 
again, or until you do a final FINISH on the database. (The 
DATATRIEVE FINISH command ends access to DBMS domains and 
records and executes a DBMS COMMIT. See Section 14.10.4 for more 
information.) Thus, DATATRIEVE applies the access mode and option 
of the most restrictive domain or DBMS record in the realm to all 
domains in that realm. 


In the preceding example, therefore. as long as VENDOR is readied 
with EXCLUSIVE WRITE, the access applied to SUPPLY is also” 
EXCLUSIVE WRITE. 
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e Tochange access to a domain or a DBMS record, you must ready the domair 
or DBMS record again. Because DATATRIEVE will ready other domains or 
DBMS records in the realm again if the new access is more restrictive, 
changing access to one domain or record may actually result in the entire 
realm being readied again. 


e If you print, modify, or store data into a domain, record, or database, 
DATATRIEVE allows you to reready with a more restrictive access only 
after you do a COMMIT, a FINISH on the record or domain, or a 
ROLLBACK. DATATRIEVE displays a message indicating it is releasing 
the collections automatically to allow such a reready. 


EXCLUSIVE WRITE access lets you store and modify records but prevents 
other users from even retrieving records from the domain until you end your 
access to it or ready it again with a different access mode. 


You can use the SHOW command to see: 


e The database records or domains that are readied (SHOW READY) 
e The fields in the records that are readied (SHOW FIELDS) 


e The sets that are made accessible, plus the access mode and access option 
with which you readied the database or domain (SHOW SETS) 


14.3.3.1. The SHOW FIELDS Command -- The following SHOW FIELDS com- 
mand displays the fields of the record types EMPLOYEE and DIVISION: 


DTR> SET DICTIONARY CDD$TOP .DTR$LIB.DEMO.DBMS 
DTR> READY EMPLOYEES, DIVISIONS : 
DTR> SHOW FIELDS 


DIVISIONS 
DIVISION 
DIV_NAME <Character string> 
EMPLOYEES 
EMPLOYEE 
EMP_ID (ID) <Number> 
EMP_LAST_NAME (LAST_NAME) <Character string> 
EMP_FIRST_NAME (FIRST_NAME) | <Character string> 
EMP_PHONE (PHONE_NUMBER) <Number> 
EMP_LOC (LOCATION) <Character string> 


No global variables are declared. 


14.3.3.2 The SHOW SETS Command -- Using the SHOW SETS command, 
you can see the sets in which the DBMS domains and record types participate. 
The SHOW SETS command identifies the domains that participate in the sets, i 
you defined domains. Otherwise, it shows the DBMS records that participate in 
each set. 
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n DATATRIEVE, because you can define a domain for each DBMS record, a 
HOW SETS command indicating the domains implicitly shows the DBMS 
2cords that participate in the sets.) 


or example, two domains, EMPLOYEES and DIVISIONS (and their associated 
xcords, EMPLOYEE and DIVISION), participate in the set MANAGES. When 
ou have defined domains, if you enter a SHOW SETS command, you see the 
omain names you defined. The EMPLOYEES domain represents the 
MPLOYEE record and the DIVISIONS domain represents the DIVISION 
cord. 


[R> SHOW SETS 
Set: MANAGES 
Owner: EMPLOYEES 
Member: DIVISIONS, automatic optional 
Set: CONSISTS_OF 
Owner: DIVISIONS 
Member: EMPLOYEES, manual optional 


Set: ALL_EMPLOYEES 
Member: EMPLOYEES, automatic fixed 


he terms “member” and “owner” refer to set characteristics that are described 
the section on finding and printing DBMS records. 


ne terms “automatic”. “manual”, “optional”, and “fixed” are discussed in the 
‘ction on erasing and disconnecting records and sets. 


1e next section on finding data in a DBMS database discusses sets further. 


4.4 Forming a DATATRIEVE Query 


nce you have defined and readied your DBMS database, you may want to: 


Find and display a record or records from that database 
Find data related to that record through DBMS set relationships 


ATATRIEVE provides you with an English-like query language for DBMS 
tabases. 


1is section discusses how to form a simple DATATRIEVE query; it is for DBMS 
ers unfamiliar with DATATRIEVE. The next section discusses how to add the 
ATATRIEVE clauses (WITHIN, MEMBER, and OWNER) to find records 

lated by a set. 
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In DATATRIEVE, you can access a single record at a time or you can work 
with a group of records. Using the DATATRIEVE record selection expression 
(RSE), you can query, print, modify, or store data in a DBMS database. A 
DATATRIEVE RSE identifies and limits the records you want to include in a 
record stream, as shown in Figure 14-3. 


DTR> FIND FIRST 3 EMPS IN EMPLOYEES WITHIN CONSISTS_OF 


fee ee, eae We 
@ ® ® @ 


restriction nameclause  rse source set clause 
clause (context variable) 


CON: WITH EMP_LOC= "45678" - SORTED BY EMPLFIRST_NAM 
®) ©) 
condition clause sort clause 
MK-01598-00 


Figure 14-3: The Parts of an RSE 


An RSE consists of the following components: 


1. An optional restriction clause (ALL or a number) -- to tell DATATRIEVE 
how many records to include in a record stream. 


2. An optional name clause -- to qualify or provide a name for the record 
source. You can use this name later to identify the record stream and to 
access records in that stream. The clause is also called a context variable 
when you use it to name a record stream or modify field names in a FOR 
loop. 


3. A required record source -- to identify an RMS, Rdb, or DBMS domain 
name, a view or network domain, a DBMS record name, an Rdb relation 
name, a collection, or a list. 


4, A DBMS set clause (WITHIN. OWNER, or MEMBER) -- to identify a set 
name and the relationship to that set. 


5. An optional selection condition (WITH Boolean expression) -- to tell 
DATATRIEVE what values to look for in a record. 


6. An optional sort clause (SORTED BY) -- to sort the record stream in the 
order you specify. 
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ne format for the RSE follows. Note that it includes the components just identi- 
2d as well as the following two additional elements: 


An optional relational clause (CROSS) -- to combine data from more than 
one domain . 
An optional reduction clause (REDUCED TO) -- to retain only unique values 


IRST n [context-var IN] rse-source 
LL 


‘ROSS [context-var IN] rse-source [OVER field-name]] [...] 
VITH boolean-expression] [REDUCED TO reduce-key [,...]] 
ORTED BY sort-key [....]] 


he format for rse-source is: 


domain-name 
collection-name 


list 

rdb-relation-name 

dbms-record-name MEMBER 
OWNER [OF] [context-name.set-name] 
WITHIN 


ote that the domain name in the preceding syntax includes DBMS domains as 
21] as Rdb, RMS, view. and remote domains. Note that the MEMBER, 

WNER, and WITHIN set-name syntax is used only with a DBMS domain name 
DBMS record name. 


yy a more complete explanation of RSE syntax, see Chapter 5 of the VAX 
ATATRIEVE Reference Manual and the chapter on writing record selection 
‘pressions in this manual. For an example of the CROSS clause, see the section 
this chapter.on using the CROSS syntax. 


1.5 Forming a DATATRIEVE/DBMS Query 


7pically, you can use two methods to form a DATATRIEVE query that accesses: 
BMS data: 


The FIND and SELECT statements, to establish a collection of records and 
point to a specific record from that collection 


The FOR statement, which uses an RSE to form a temporary record stream 
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These statements are discussed and illustrated in the next sections. 


14.5.1 Forming a DATATRIEVE Collection of DBMS Records 


You can access DBMS data in DATATRIEVE by forming a collection. A collec- 
tion is a group of records that you can access until you: ; 


e Form anew collection (unless you assign a name to the new or old 
collection). 


° Remove the collection with the RELEASE command. 


¢ Finish the domain that owns the collection using the FINISH command. 


14.5.1.1. Using the FIND Statement -- You form a collection using the 
DATATRIEVE FIND statement. You can create collections from a readied 
DBMS domain or from a DBMS record in a database you have readied through 
DATATRIEVE. 


When you form a collection, DATATRIEVE gives that collection the name 
CURRENT. You can access this collection with the name CURRENT, or you car. 
assign an additional name for a collection and use this name to access the 
collection. You use the name clause as illustrated in the RSE format to name a 
collection. 


If you name a collection, it is not deleted when you form another collection. 
Therefore, you can have several named collections of records available at any tim 
in DATATRIEVE. 


The following example, for instance, forms a collection from the DBMS record 
EMPLOYEE. readied when you readied the PARTS DB database: 


1. Form a collection of the first five employees and assign the name EMP to 
that collection. 


2. Form a second collection by limiting the EMP collection to those employee 
with EMP LOC = 45678 and assign the name EMP45. 


3. Show that DATATRIEVE retains information about both collections 
EMP45 (also CURRENT) and EMP. 


4. Print the CURRENT collection. 
5. Print the EMP collection. 
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‘R> READY EMPLOYEE 


‘R> FIND FIRST & EMP IN EMPLOYEE <C we eee we neenee (1) 
' records found 
‘R> FIND EMP45 IN EMP WITH EMP_LOC = "45678" <----- (2) 
' records found] 
‘R> SHOW COLLECTIONS lo recn ne eceenee (3) 
‘llections: 
EMP45 (CURRENT) 
EMP 
‘R> PRINT CURRENT Cree ew eeeeecee (4) 
Phone 

ent Last Name-~---------- First Name Number Loc 

998 HILL OLA 124567 45678 
(2234 HORTI BRUCE 124567 45678. 
‘R> PRINT EMP Kl oven nreeeenn= (5) 

Phone 

ent Last Name----------- First Name Number Loc 
5624 FRASER BOB 8902345 23456 
2333 HOFFMAN MIKE 4568901 89012 

998 HILL OLA 124567 45678 
(2234 HORTI BRUCE 124567 45678 
7777 PASCAL RICHARD 4568901 89012 


ote that you can still access the records in the EMP collection after you create a 
cond collection with the FIND statement. As long as you name the collections, 
ATATRIEVE retains them when you create new collections. 


you name a collection, you can use this name as a context variable in an RSE to 
odify a record stream. Later sections contain examples showing how you can do 
is. 


1.5.1.2 Using the SELECT Statement -- After you form a collection, you use 
e SELECT statement to choose a record from that collection. This selected 
cord is the target of other DATATRIEVE statements such as PRINT,. 
ODIFY, and ERASE. The SELECT statement establishes DBMS currency for 
record. 


ou can specify the record you want to access either by using an integer 
ELECT 5 gets the fifth record of the collection) or by such syntax as FIRST, 
EXT, LAST, and so on. 
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In the following example, the SELECT statement: 


1. Selects the first record in the EMP45 collection, which is also the 
CURRENT collection. When you do not specify a collection name, the 
SELECT statement defaults to the first record in the CURRENT 
collection. 


2. Selects the second record in the EMP collection. 


DTR> SELECT lo none o-oo nnn nnee $+ + (1) 
DTR> PRINT 
Phone 
Ident Last Name----------- First Name Number Loc 
998 HILL OLA 124567 45678 
DTR> SELECT 2 EMP Sl cree reece ee ern nce e mene nenne (2) 
DTR> PRINT 
Phone 
Ident Last Name----------- First Name Number Loc 
12333 HOFFMAN MIKE 4568901 89012 


For a complete discussion of the FIND and SELECT statements, see the FIND 
and SELECT statements in the VAX DATATRIEVE Reference Manual. 


14.5.2 Forming a Record Stream of DBMS Records 


The FOR statement differs from using collections in that it creates a temporary 
record stream that DATATRIEVE knows about only while it is executing that 
statement. It places locks on fewer DBMS records than a FIND statement. 


DATATRIEVE can access each record in that stream one by one, displaying, 
printing, or modifying each record according to your specifications. As each 
record is accessed, it becomes current. 


For instance, in the following example, you: 


1. Forma temporary DATATRIEVE record stream of employee records with 
EMP LOC = 45678 


2. Display only those employees in the record stream 


3. Try to print the CURRENT collection, which does not exist 
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TR> READY EMPLOYEES 


TR> FOR EMPLOYEES WITH EMP_LOC = "45678" 9 <----------- (1) 
Looking for statement] 
ON> PRINT EMPLOYEE < woeeecnenee (2) 
Phone 

dent Last Name----------- First Name Number Loc 

998 HILL OLA 124567 45678 
22234 HORTI BRUCE 124567 45678 
11141 SCHATZEL BETH 124567 45678 
12322 THOMPSON STEPHEN 124567 45678 
12345 HUNTER BUTCH 124567 45678 
TR> SHOW CURRENT << enennen- (3) 


current collection has not been established. 


4.6 Forming a DATATRIEVE/DBMS Query of Data Related by 
Sets 


1 the previous section, you used simple DATATRIEVE queries to access infor- 
iation from a single DBMS record or domain. 


lote that DATATRIEVE also makes set information available when you ready a 
omain. In the following sections, you access information from both the data in a 
ngle record and data in records related through information in a set. 


s with DBMS data in a single record, you can use the FIND and SELECT syn- 
ix to form collections, or you can use the FOR syntax to create a temporary 
cord stream. | 


‘ote two important concepts about using DATATRIEVE statements to access 
‘BMS data related by set information: 


You must use either the FIND and SELECT or the FOR statement to estab- 
lish the single record context, called currency, in DBMS. DBMS needs this 
single record context to find related records and sets. 


You must specify a DBMS set name to identify the sets in which a record 
participates, unless you use the Context Searcher. (See Section 14.6.4.) 
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When you access information through DBMS sets, you access: 


e First, a particular record from a domain or record (for example, a department 
from the DIVISIONS domain) | 


e Second, data related to that record from other DBMS domains or records . 
through a set (for example, employees from the EMPLOYEES domain 
related through the set CONSISTS OF) 


The examples in this section use the set CONSISTS OF. It represents the rela- 
tionship between a department in an organization (DIVISIONS domain) and the 
employees that make up that department (EMPLOYEES domain). Figure 14-1 
shows this relationship. 


The following sections illustrate DATATRIEVE syntax you use to access infor- 
mation in sets. 


14.6.1. Forming Collections of DBMS Set Data 


As with data in a single DBMS record, you can form a collection of DBMS data 
related through set information. You can then access those records by the collec- 
tion name. 


In the following example, for instance, you form a collection (DIV) from the 
DIVISIONS domain. You form a second collection (EMP) of employee records. 
The employee records in EMP collection are related to the selected record from 
the DIV collection. DATATRIEVE now knows about both collections, DIV and 
EMP. You can print records from both of these collections: 


1. Use the FIND statement to create a collection of records from the 
DIVISIONS domain. The SELECT statement identifies a single record 
occurrence and establishes context (currency in DBMS) with the set 
information. 


2. Use the FIND statement again to establish a collection of employee infor- 
mation from the EMPLOYEES domain. By using the WITHIN set-name 
syntax, you identify the set that you want DATATRIEVE to use. This set 
identifies the employee records related to the SOFTWARE division. 
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TR> SET DICTIONARY CDD$TOP.DTR$LIB.DEMO.DBMS 
TR> READY DIVISIONS, EMPLOYEES 


TR> FIND DIV IN DIVISIONS WITH DIV_NAME = "SOFTWARE" | 


1 record found] | 1 
TR> SELECT | 


TR> FIND EMP IN EMPLOYEES WITHIN CONSISTS_OF 
3 records found] 
TR> PRINT DIV_NAME, EMPLOYEE OF EMPLOYEES 


| 
| 
| 
| 
Phone | 
| 
| 
| 
| 


ivision Name---Ident Last Name----First Name Number Loc 2 

DF TWARE 23451 HUTCHINGS | BRUCE 2346789 67890 

OF TWARE 43215 IACOBONE ANTHONY 124567 45678 

OF TWARE 77777 PASCAL | RICHARD 4568901 89012 | 
a ee + 

lote that: 

1. You must identify a single record occurrence using FIND and SELECT so 


that DATATRIEVE can establish context een: in DBMS) for the 
related set information. 


In the first part of the example. DATATRIEVE uses the selected single 
record, SOFTWARE, to establish context for the set information. 


Specify the set that contains pointers relating the data from one domain (or 
DBMS record) to another. 


In the second part of the example, the WITHIN clause tells DATATRIEVE - 
to look at the single occurrence of the set CONSISTS OF. The single set 
occurrence contains pointers that point from the single record occurrence 
DATATRIEVE currently knows about. the SOFTWARE division, to related 
records in the domain, EMPLOYEES. | 


4.6.2 Forming Record Streams of DBMS Set Data 


‘ou can use the FOR loop to access the information from two domains. The 
ested FOR loop in the following example creates two record streams ane allows 
ou to access records from each stream. In this example: 


L. 


iw 
° 


You form a temporary record stream of all records from the DIVISIONS 
domain with a DIV NAME that contains the string VT (groups that develop 
video terminals). You assign that record stream a name (VID). 


You form a second temporary record stream of the records from the related 
employee records in the EMPLOYEES domain identified by the set 
CONSISTS OF 
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3. You print the division name and the related employee information. 


DTR> FOR VID IN DIVISIONS WITH DIV_NAME CONT "VT" <------- (1) 

CON> FOR EMP IN EMPLOYEES WITHIN CONSISTS_OF <Ccocenn= (2) 

CON> PRINT VID.DIV_NAME, EMP.EMPLOYEE <coeneee (3) 

Phone 

Division Name------- Ident Last Name------ First Name Number Loc 
VT100 DEVELOPMENT 65437 FRANK BEBI 4568901 89012 
VT100 DEVELOPMENT 12333 HOFFMAN MIKE 4568901 89012 
VT100 DEVELOPMENT 54332 IGLESIAS RAFAEL 2346789 67890 
VT52 DEVELOPMENT 9867 FLETCHER BRUCE 124567 45678 
VT52 DEVELOPMENT 43221 HYNES RICH 8902345 23456 


Notice that you can name the record stream in the FOR statement (VID) and use 
that name to qualify a field name (VID.DIV NAME). In this example, the qualify- 
ing name is not necessary to identify fields uniquely. 


FOR loops allow you to access records more quickly than FIND statements. Note 
that when you use a FOR loop, you need not use the SELECT syntax; 
DATATRIEVE selects a single record each time through the loop. For more 
information on the FOR loop, see the FOR statement in the VAX DATATRIEVE 
Reference Manual. 


14.6.3 Using OWNER and MEMBER Clauses to Identify Sets 

In the previous section, you used the WITHIN clause to identify: 

e The domain name (EMPLOYEES) from which you wanted the employee 
data 


e The set name (CONSISTS OF) that identified the employee record you 
wanted 


The WITHIN clause allows you to specify a set name without having to know if 
the domain is a member or owner of the set. 


There are two additional clauses of the record selection expression that allow you 
to specify access to records through DBMS sets: 


e The MEMBER clause 
° The OWNER clause 


The OWNER and MEMBER clauses specify whether a record is a member or an 
owner of a set. In many cases, you can use the WITHIN clause in place of the 
MEMBER and OWNER clauses. The SHOW SETS command lets you see 
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vhether a domain is a member or an owner of a set: 


TR> SHOW SETS 
Set: MANAGES 


Owner: EMPLOYEES <a (1), 
Member: DIVISIONS, automatic optional 
Set: CONSISTS_OF 


Owner: DIVISIONS ee (2) 
Member: EMPLOYEES, manual optional 


Set: ALL_EMPLOYEES < --nnne-e- (3) 
Member: EMPLOYEES, automatic fixed 


‘he SHOW SETS command indicates that: 


1. The EMPLOYEES domain (in DBMS, the EMPLOYEE record) owns the 
set MANAGES. The DIVISIONS domain (in DBMS, the DIVISION record) 
is a member of the set MANAGES. 


2. The DIVISIONS domain (in DBMS, the DIVISION record) owns the set 
CONSISTS OF. The EMPLOYEES domain (in DBMS, the EMPLOYEE 
record) is a member of the set CONSISTS OF. 


3. The EMPLOYEES domain is also a member of the ALL EMPLOYEES 
set, a system-owned set. 


Note 


A system-owned set is a set owned by DBMS instead of a user-defined 
record. System-owned sets have only one occurrence in the database 
and are used for relationships with a large number of member occur- 
rences, or as entry points into a database. For more information on sys- 
tem owned sets, see the VAX DBMS Database Design Guide. 


igure 14-4 shows all these set relationships. 


he following sections show you how to use the MEMBER and OWNER clauses 
» access DBMS records. 
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DIVISIONS SYSTEM 







ALL __EMPLOYEES 
CONSISTS_OF | ° 


EMPLOYEES 


MK-01139-00 
Figure 14-4: Set Relationships in Sample DBMS Database 


14.6.3.1. The MEMBER Clause -- The MEMBER clause lets you access the 
member records of a set. Conceptually, you are telling DATATRIEVE to “look 
down” from a specified position (determined by a FIND/SELECT or a FOR state- 
ment) and find the members of the set that are linked to the selected record. 


For example, because EMPLOYEES is a member of the set CONSISTS OF, you 
can use the MEMBER syntax rather than the WITHIN syntax you used in the 
previous section: 


DTR> FIND DIV IN DIVISIONS WITH DIV_NAME = "SOFTWARE" 
DTR> SELECT 

DTR> FIND EMPLOYEES MEMBER OF CONSISTS_OF 

DTR> PRINT ALL DIV_NAME, EMPLOYEE 


Phone 
Division Name------- Ident Last Name----------- First Name Number Lo 
SOF TWARE 23451 HUTCHINGS BRUCE 2346789 678 
SOF TWARE 43215 IACOBONE ANTHONY 124567 456 
SOF TWARE 77777 PASCAL RICHARD 4568901 890 


14.6.3.2 The OWNER Clause -- The OWNER clause tells DATATRIEVE to 
"look up” from a position in the database, thereby giving you access to the owner 
record of a set. The OWNER clause operates like the MEMBER clause; the only 
difference is in the direction that DATATRIEVE looks. 


For example. you know an employee named Richard Pascal and want to know 
the division in which he works. Because DIVISIONS is the owner of the set 


14-24 Using DATATRIEVE with DBMS 


YONSISTS OF, you: 


1. Form a record stream with the single employee record 


2. Use the OWNER clause with the CONSISTS OF set to find the depart- 
ment in which the employee works 


TR> FOR EMP IN EMPLOYEES WITH EMP_LAST_NAME= "PASCAL" <nnnHe-- (1) 
ON> PRINT ALL EMPLOYEE, DIV_NAME OF 
ON> DIVISIONS OWNER OF CONSISTS_OF <nreeeee (2) 
TR> : 

Phone 
dent Last Name----------- First Name Number Loc Division Name--- 
7777 PASCAL RICHARD 4568901 89012 SOFTWARE 
TR> 


4.6.4 Using the SET SEARCH Command to Access Sets 


is a DATATRIEVE user, you can use the SET SEARCH command to establish 
ontext for list fields in records or for fields in hierarchical views. 


1 addition, as a DATATRIEVE user accessing a DBMS database, you can use 
1e SET SEARCH command to search for records related by set information. 
‘ou use this command in place of the WITHIN, OWNER, or MEMBER clauses. 


he SET SEARCH command instructs the DATATRIEVE Context Searcher to 
noose the shortest route between DBMS record types when executing a PRINT 
satement. DATATRIEVE resolves the context for you so that you need not 
gecify the set relationship. 


he following example executes a SET SEARCH statement and prints the 
slated division data without requiring you to specify the set CONSISTS OF: 


[R> SET SEARCH 

([R> FIND FIRST 1 EMPLOYEES 

| record found] 

[R> SELECT 

[R> PRINT DIV_NAME 

»t enough context. Some field names resolved by Context Searcher. 


-vision Name---~---- 
I1G@ STOCKROOM 
*R> 
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The following example walks through all occurrences of the set type 

CLASS PART, instructing DATATRIEVE to display on your terminal only the 
class code number, part identification numbers, and part descriptions of records 
owned by CLASSES: 


DTR> SET SEARCH 
DTR> PRINT CLASS_CODE, PART_ID, PART_DESC OF CLASSES 
Not enough context. Some field names resolved by Context Searcher. 


Code 
BR 


BT 
BU 


Part 
Number 


BR-1234-56 
BR-3467-91 
BR-8901-23 
BT-0456-78 
BT~1634-56 
BU-0345-67 
BU-1045-68 


CG-3256-40 
CG-3454-38 
CG- 4567-89 
CG-8767-78 
CG-8901-23 
CG-9435-61 
CG-9562-13 


VT100 
TERMINAL TABLE VT52 
FREE-STANDING FRAME ASSEMBLY 


VT100 KEYBOARD KED ASSY 
PLASTIC KEY NUM. STYLE C 
PLASTIC KEY ALPHA. STYLE A 
VT100 SCREEN | 
VT100 HOUSING 

KEY BASES 

VT100 NUMERIC KEY CAP SET 


In this case, the Context Searcher found many records. You can find the owners 
and members of database sets by using the PRINT and SET SEARCH state- 
ments. It is important to remember that SET SEARCH guesses: it always takes 
the shortest route in a set structure and. therefore, might not return the right 
answer. 


Note that if you did not use the Context Searcher in the preceding example, the 
full DATATREIVE query would use an inner print list. For the statement 
"PRINT CLASS CODE, PART ID, PART DESC OF CLASSES”, you would 
need the following query: 


DTR> PRINT CLASS_CODE, ALL PART_ID, PART_DESC OF 
CON> PART_S MEMBER OF CLASS_PART OF CLASSES 
DTR> 


The expanded statement includes an inner print list. 


The following example readies two more domains and instructs DATATRIEVE t 
display the name and description of the parts supplied by the vendor with the 


14-26 Using DATATRIEVE with DBMS 


1ame "QUALITY COMPS”: 


ITR> SET SEARCH 

ITR> READY SUPPLIES, VENDORS 

ITR> PRINT VEND_NAME, PART_DESC OF 

‘ON> VENDORS WITH VEND_NAME = "QUALITY COMPS" 

iot enough context. Some field names resolved by Context Searcher. 


UALITY COMPS 

T100 KEYBOARD ASSY 
UMERIC KEYPAD FRAME 
T52 HOUSING 


‘his PRINT statement resulted in the display of all parts associated with the 
pecified vendor. The PRINT statement is equivalent to: . 


TR> PRINT VEND_NAME, ALL ALL PART_DESC OF PART_S OWNER OF 

ON> PART_INFO OF SUPPLIES MEMBER OF VENDOR_SUPPLY OF VENDORS WITH 
ON> VEND_NAME = "QUALITY COMPS" 

4.7 Finding Data from Two or More Domains 


A previous sections, you found records from several domains by first finding a 
ingle record in one domain and then related data in a second domain through a 
et relationship. 


\ATATRIEVE provides several ways for you to access records from two or more 
omains, in addition to using the simple DATATRIEVE queries shown in the pre- 
ious sections. These methods become particularly important when the data you 
ant may reside in more than two domains. These methods include: 

Combining the MEMBER and OWNER clauses to “walk the DBMS sets” 


Using the CROSS clause of the RSE to join the data from several records or 
domains 


Defining a domain called a VIEW domain that lets you form simple queries 
and keeps the complex set relationships in the domain definition 


he example used in the following sections uses the VENDORS, PART S, and | 
UPPLIES domains. The data in the VENDORS and PART S domains has what 
BMS calls a many-to-many relationship. 


or example: 


A single vendor might supply many different parts. 
A single part might be supplied by many different vendors. 
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In a DBMS database, there cannot be a direct relationship between records 
(DATATRIEVE domains) that have a many-to-many relationship. If you attempt 
to select a particular vendor from the VENDORS domain, for instance, and then 
try to display an associated part from the PART S domain, DATATRIEVE gives 
you an error message indicating you have not established the correct context for 
parts: 


DTR> READY VENDORS, SUPPLIES, PART_S 

DTR> FIND VENDOR WITH VEND_ NAME = TOUALTIY COMPS" 

[1 record found] 

DTR> SELECT ‘ 

DTR> FIND PART_S WITHIN VENDOR_SUPPLY 

Set "VENDOR_SUPPLY" is undefined or used out of context. 
DTR> 


To relate the parts and vendor data, you must go through a third domain or 
record that is owned by both the PARTS and VENDORS domains. 


_ Figure 14-5 shows the VAX DBMS UPECSeD MON of this many-to-many 
relationship. 


VENDORS 


PART _INFO VENDOR_SUPPLY 





SUPPLIES 
MK-01135~00 


Figure 14-5: DBMS Set Relating Three Domains 


14.7.1 Walking the Sets 


Suppose you want information that involves access to PARTS, VENDORS: and 
SUPPLIES. You want: 


e The names for a specific vendor (VENDORS domain) 
e The types of parts that vendor supplies (PARTS domain) 
e Delivery lag time for that part (SUPPLIES domain) 
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‘do this, you: 


Ready all three DBMS domains. These READY commands also ready the 
set relationships among the domains. 


Find a vendor (for example, the company called QUALITY COMPS). 


Find the parts supplied by QUALITY COMPS. Since you cannot directly 
access part information in the PART S domain from the VENDORS 
domain, you must go through the SUPPLIES domain. To do this you: 


a. __ Find all the member records in SUPPLIES related to the selected 
VENDOR record. 


b. Form a FOR loop that establishes a single record context for each 
record in the SUPPLIES domain. Note that when you use a FOR loop, 
you do not use the SELECT statement. 


c. Print the three parts associated with that SUPPLIES record by using 
the OWNER clause to find related parts through the PART INFO set. 
tice that you must continue to provide a single record context for 


.TATRIEVE with either the FIND and SELECT statements or the FOR loop. 


(> SET DICTIONARY CDD$TOP .DTR$LIB.DEMO.DBMS 


‘> READY VENDORS, PART_S, SUPPLIES <o nnn ee ee (1) 
'> 

> FIND VENDORS WITH VEND-NAME = "QUALITY COMPS" < ------- (2) 
record found] 

'> SELECT 

> PRINT VEND_ID, VEND_ NAME 

ndor 

ID So SSeS SiS Vendor Name--------------- 


89012 QUALITY COMPS 


> 


> FIND SUP IN SUPPLIES MEMBER OF VENDOR_SUPPLY <---- (3a) 
records found] 

> PRINT SUP 

record selected, printing whole collection. 


g Type Lag Time 
MEMO 4-6 WEEKS 


REPR 1-2 MONTHS 
WSUP 7-8 WEEKS 


(continued on next page) 
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DTR> FOR SUP <---- (3b) 


CON> PRINT PART_ID, PART_DESC OF <---- (3¢) 
CON> PART _ S OWNER OF PART_INFO 

Part 

Number: “seer eres<Srese se Part Description-~--------~-~----- 


CG-3161-34 VT100 KEYBOARD ASSY 
CG-1052-00 NUMERIC KEYPAD FRAME 
CG-0956-78 VT52 HOUSING 

DTR> 


14.7.2 Using the CROSS Clause 


You can combine records from several DBMS domains (or DBMS records readie 
by the READY command for databases) with the CROSS clause from the record 
selection expression. The CROSS clause lets you compare and combine records 
from two or more sources into a single record stream. It forms temporary rela- 
tionships between records stored in different domains (or DBMS records) and let 
you treat the data as though it were derived from one domain or record. You can 
also combine data from DBMS records with Rdb or RMS records by using a 
CROSS clause. | 


In the following example, you use the three domains from the previous section. 
Using the CROSS clause, you combine several domains in one collection and 
write queries against that collection. In this example, you: 


1. Form a named collection (QUAL PART) of the vendor record with a vendo 
name of QUALITY COMPS. 


2. Use the CROSS clause to join this vendor collection with the two other 
domains. You can do this with a FIND or FOR statement that uses two 
cross clauses. 


3. Display the vendor and all the parts made by that vendor from the 
_ VENDORS and PART S domains. 


DTR> FIND QUAL_PART IN VENDORS WITH VEND_NAME = "QUALTIY COMPS" (1) 
[1 record found] 


DTR> FIND QUAL_PART CROSS Kroenen ne ne (2) 
CON> SUPPLIES MEMBER VENDOR_SUPPLY CROSS 

CON> PART_S OWNER PART_INFO 

[3 records found] 


DTR> PRINT ALL VEND_ID, PART_ID, PART_DESC,SUP_TYPE <----------- (3) 
Vendor Part 

ID Nunber .+F Sareea See Part Description--~------ Type 
55789012 CG-3161-34 VT100 KEYBOARD ASSY MEMO 
55789012 CG-1052-00 NUMERIC KEYPAD FRAME REPR 
55789012 CG-0956-78 VT52 HOUSING WSUP 
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4.7.3. Using View Domains 


f you define domains for each DBMS record, you can use DATATRIEVE view 
omains to access data in those records. You cannot form views of DBMS records 
eadied by the READY command for databases. 


ou can define a simple DATATRIEVE view domain to see a subset of fields from 
single domain. The following view, for example, lets you define a view domain 
hat accesses only three fields in the PART S domain. This view is further 

efined by the Boolean expression that limits the records to those with 

‘ART SUPPORT = "FS": 


TR> DEFINE DOMAIN VIEW_PARTS_PUBLIC of PART_S USING 
FN> O1 PARTV OCCURS FOR PART_S WITH PART_SUPPORT = "FS". 


FN> 03 PART_ID FROM PART_S. 
FN> 03 PART_DESC FROM PART_S. 
*N> 03 PART_PRICE FROM PART_S. 
7N> 3 

[R> 


4.7.3.1 Hierarchical Views -- You can also use view domains to combine 
xcords from several DBMS domains. A view domain that describes data from 


1ore than a single domain and does not use a CROSS clause is called a hierarchi- 
al view. 


hierarchical view domain, unlike a CROSS clause (which also combines data 
om two or more domains), lets you define the relationship of records from sev- 
‘al domains and store it in the CDD. 


nce you define this relationship, you can display and modify data without having 
» consider set relationships. You can read and modify selected records from two 
‘more domains as if the data were all in one domain. 


ote that because data is not stored in a view, you cannot use a STORE state- 
ent with a view domain as your record source. 


ne following view combines the fields DIV NAME from the domain DIVISIONS 
id EMP ID and EMP LAST NAME from EMPLOYEES. Note that once you 


‘fine the relationship, you can ready the domains and print records from those 
ymains. 


‘R> SHOW DIV_VIEW 
MAIN DIV_VIEW OF DIVISIONS, EMPLOYEES USING 
GRP OCCURS FOR DIVISIONS. 
02 DIV_NAME FROM DIVISIONS. 
O02 WORKERS OCCURS FOR EMPLOYEES WITHIN CONSISTS_OF. 
04 EMP_ID FROM EMPLOYEES . 
04 EMP_LAST_NAME FROM EMPLOYEES. 


(continued on next page) 


Using DATATRIEVE with DBMS 14-31 


DTR> READY DIV_VIEW 
DTR> PRINT FIRST 5 DIV_VIEW 


Division Name------~ Ident Last Name----------- 
LA34 DEVELOPMENT 65438 FRATUS 
SOF TWARE 23451 HUTCHINGS 


43215 IACOBONE 
77777 PASCAL 
RMOS DEVELOPMENT 99998 PAYNE 
ENG BUILD & TEST 75624 FRASER 
55675 HORYMSKI 
O HUMPHRY 
9789 MASE 
66666 PARVIAINEN 
VT100 DEVELOPMENT 65437 FRANK 
12333 HOFFMAN 
54332 IGLESIAS 


Note that when you define a view domain with two or more domains, the data is 
displayed in hierarchical form, unless you use a CROSS clause in the view 
definition. 


In the previous example, the view of two domains displays one occurrence of the 
field DIV NAME and a variable number of employees. In DATATRIEVE, to 
access individual fields in this hierarchical structure, you must use specialized 
DATATRIEVE syntax for retrieving values from list fields. See Chapter 6 for a 
complete explanation of this syntax. 


14.7.3.2 Flat Views -- When you combine a view domain with the relational 
CROSS clause. it flattens the hierarchical relationships. The following flat view 
combines fields from the domains VENDORS, SUPPLIES, and PART S: 


DTR> DEFINE DOMAIN FLAT_PART_VIEW OF PART_S, VENDORS, SUPPLIES USING 
DFN> O1 A OCCURS FOR PART_S CROSS SUPPLIES MEMBER OF PART_INFO CROSS 
DFN> VENDORS OWNER OF VENDOR_SUPPLY. 


DFN> 02 PART_ID FROM PART_S. 
DFN> 02 SUP_TYPE FROM SUPPLIES. 
DFN> 02 VEND_NAME FROM VENDORS. 
DFN> ; 

DTR> 


The biggest advantage of defining a flat view is that you can refer to each of the 
fields more easily than in a hierarchical view. That is, you need not use an inner 
print list; you can access hierarchical fields as though they belong to a single 
record. The following example prints the first five records in a flat view and then 
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splays a specific record from the VENDORS domain: 
‘R> READY FLAT_PART_VIEW 
R> PRINT FIRST 5 FLAT_PART_VIEW 


Part 
Number Type ----~-~----~---- Vendor Name--------------- 


~3556-78 MEMO U.S. SEALS 
1110-85 REPR HIGH ENERGY CORP 
-7896-12 REPR EMI TECHNOLOGY INC 


-8767-78 WSUP ELECTRONIC SUPPLY CO. 
~4058-32 CALL SYSTEMS HDWE REPS 


R> PRINT VEND_NAME WITH PART_ID="CF405832" 


STEMS HDWE REPS 


4.8 Sample Procedures Using DBMS Domains 


yu can define DATATRIEVE procedures that let you query a VAX DBMS. 
itabase. A DATATRIEVE procedure is a fixed sequence of commands and state- 
ents that you create, name. and store in the Common Data Dictionary. For 
most any series of commands and statements you use repeatedly, you can save 
urself time by defining a procedure. . 


procedure can contain any number of the following DATATRIEVE elements: 


Full DATATRIEVE commands and statements 
Command and statement clauses and arguments 


Comments 


) define a procedure. you enter the DEFINE PROCEDURE command at the 
rR> prompt. DATATRIEVE prompts with the DFN> prompt to indicate that 
u can enter a procedure definition. You end the procedure definition with an 
ND PROCEDURE keyword on a line by itself. 


wr example, the following procedure searches for a division associated with the 
iployee name you specify. 
Ready the domains EMPLOYEES and DIVISIONS. 
Form a temporary record stream of the employee record you want. The 


prompt option (*) lets you specify the employee’s name when you execute 
the procedure. 
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3. Display the owner of.the CONSISTS OF set of which the employee is a 
member. 


DTR> DEFINE PROCEDURE EMPLOYEE_SEARCH 


DFN> READY EMPLOYEES, DIVISIONS ae BARGES SRE SERRE (1) 
DFN> PRINT "This procedure searches to find" 

DFN> PRINT "the division associated with" 

DFN> PRINT "the employee you specify." 

DFN> PRINT SKIP 


DFN> FOR EMPLOYEES WITH EMP_LAST_NAME = So seterereneee (2) 
DFN> «*."the employee’s last name in capital letters" 
DFN> PRINT DIVISIONS OWNER CONSISTS_OF Serres (3) 


DFN> COMMIT EMPLOYEES, DIVISIONS 
DFN> END_PROCEDURE 
DTR> 


To execute the procedure, enter: 


DTR> :EMPLOYEE_SEARCH 


This procedure searches to find 
the division associated with the 
employee you specify. 


Enter the employee’s last name in capital letters: ZOTTO 


Division Name------- 


RKOS DEVELOPMENT 


For information on the COMMIT statement, see Section 14.10.4. In another 
example, you can define a procedure to find a vendor name and all the parts pro- 
duced by that vendor. This procedure: 


1. Readies the domains VENDORS, SUPPLIES, and PART S 


2. Uppercases the vendor names you enter following the prompt and finds 
them in the VENDORS domain 


3. Finds the related records in the SUPPLIES domain 


4, Uses the context from the FOR statement in step 3 to print the related 
part number from the PART S domain 


5. Finishes the readied domains 
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[R> DEFINE PROCEDURE VENDOR_PARTS 


"N> READY VENDORS, SUPPLIES, PART_S Bree eieats (1) 


"N> PRINT "This procedure searches to find" 
"N> PRINT "the part associated with " 

"N> PRINT "the vendor you specify." 

"N> PRINT SKIP 


"N> FOR VENDORS WITH VEND_NAME = < recenscencnee (2) 
?N> FN$UPCASE(«.'" Name of Vendor ") 

"N> FOR SUPPLIES MEMBER OF VENDOR_SUPPLY K wnnenncenennne (3) 
"N> PRINT ALL PART_ID OF PART_S OWNER OF PART_INFO <-------------- (4) 
"N> FINISH VENDORS, SUPPLIES, PART_S << raneencennenee (5) 


"N> END_PROCEDURE 
[R> 


o execute the procedure. enter: 


[R> :VENDOR_PARTS 

11s procedure searches to find 

1e part number associated with the 
*¢ndor you specify. 


iter Name of Vendor: quality comps 


Part 
Number 


i~ 3162-34 
i~ 1052-00 
i-0956-78 


'R> 


4.9 Modifying Individual Fields in a Record 


ou can modify a field in a DBMS record just as you do in an RMS domain using 
ie DATATRIEVE MODIFY statement. The following example modifies the 


MP PHONE field of the EMPLOYEE record: 


.. Ready the DBMS EMPLOYEES domain for WRITE access. 
2, Modify the field EMP PHONE. 


"R> READY EMPLOYEES WRITE <------------ (1) 
*R> 
"R> MODIFY EMP_PHONE OF Cinteeetennen (2) 


IN> EMPLOYEES WITH EMP_ID = "53456" 
iter EMP_PHONE: 5345 
"R> 
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For a complete discussion of the MODIFY statement in DATATRIEVE, see 
Chapter 4. Using the syntax described in Chapter 4, you can modify all or some 
fields within a single record occurrence or within a collection of records. 


If you change a field that has a DBMS CHECK clause, DBMS checks the value 
you enter for that field. If the value violates the CHECK clause, DATATRIEVE 
returns a DBMS error and does not prompt for the field. 


In general, modifying a record affects at least the data portion of the record. If, 
however, you modify a field that is a sort key or a hash key for a set, DBMS auto: 
matically reorders the members of the set. See the VAX DBMS Introduction to 
Data Manipulation for more information about modifying sort or hash keys. 


14.10 Storing DBMS Records and Modifying Sets 


When you add a record to a DBMS database, you can affect other members of the 
sets in which the new record participates. You may also wish to disconnect a 
record from a particular set occurrence and perhaps reconnect it with another set 
occurrence. 


DATATRIEVE provides you with several statements you can use with DBMS 
domains to manipulate records as owners and members of sets: 


e The STORE statement -- adds a new record to the database and automati- 
cally connects the record to each set of which it is an automatic member 


e The CONNECT statement -- connects a selected member record to a set 


@ The DISCONNECT statement -- disconnects a member record from each set 
you specify (you cannot disconnect owner records) 


e The RECONNECT statement -- disconnects a member record from each set 
occurrence you specify and connects the record to another set occurrence yo 
specify (you cannot reconnect owner records) 


14.10.1 Storing and Connecting Records 


When you store a new record or when you want to connect a particular record to : 
set occurrence, the procedure you use depends on whether the set is an automatic 
or manual member of a set. 
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nsertion into a set can be: 


Automatic 


DATATRIEVE automatically inserts the record into the set when you 
store it. ' 


Manual 


After modifying or storing the record, you can connect it to the set of which 
it is a member or leave it unconnected in the database. 


‘or example. when you use the SHOW SETS command you can see the charac- 
eristics identified by DATATRIEVE for member domains: 


TR> SET DICTIONARY CDD$TOP .DTR$LIB. DEMO. DBMS 
TR> READY VENDORS, SUPPLIES 
TR> SHOW SETS 


et: VENDOR_SUPPLY 
Owner: VENDORS ® 
Member: SUPPLIES, automatic fixed 


et: ALL_VENDORS 
Member: Vendors, automatic fixed 


UPPLIES is an automatic member of the set VENDOR SUPPLY. The auto- 
iatic characteristic indicates that when you store a new supplies record, it is 
utomatically connected to the set VENDOR SUPPLY. 


UPPLIES is also a member of a system-owned set ALL VENDORS. It auto- 
iatically participates in this set. ; 


he fixed characteristic means that the domain SUPPLIES must be a member of 
1e set. Also, the record occurrence cannot be connected to any set occurrence 
cher than the one to which it belongs when it is stored. For example, a particular 
UPPLY record cannot be connected to any other vendor through 

ENDOR SUPPLY than the one it was associated with at the time the record 

as stored. This characteristic is discussed in the section on erasing and discon- 
acting records from sets. 


he following two sections discuss automatic and manual insertion in a set. 


1.10.1.1 Automatic Insertion -- If a record is an automatic member of a set, 
hen you use the DATATRIEVE STORE statement to store new records in the 
BMS database. the record is automatically inserted into the set. 
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If you are storing a new record and only want to connect it with a system-owned 
set. you do not have to establish context to insert a record. After readying the 
domain for WRITE access, all you need to store a record into a system-owned set 
is a STORE statement. For example: 


DTR> READY EMPLOYEES WRITE 
DTR> STORE EMPLOYEES 

Enter EMP_ID: 53456 

Enter EMP_LAST_NAME: WINSLEE 
Enter EMP_FIRST_NAME: JOANNE 
Enter EMP_PHONE: 5324 

Enter EMP_LOC: AS 


DTR> 


The new record automatically becomes a member of system-owned sets in which 
the record (domain in DATATRIEVE) participates. For example, a new employees 
record is automatically part of the ALL EMPLOYEES set in this example. 


If a newly stored record is an automatic member of a set not owned by the 
system, though DATATRIEVE automatically connects the record to the set in 
which the record participates, you must provide the context for the set occurrence 
to which you want to connect the record. . 


Therefore, when you use the STORE statement: 


e You use the CURRENCY clause to provide context for automatic members 
of sets that are not owned by the system 


¢ The record is automatically connected to each set of which it is an automatic 
member 


As with the display and print operations, DATATRIEVE uses the single-record 
context you supply to identify the set occurrence (and sometimes to select the 
position in that occurrence) when you modify sets or store records. If you fail to 
supply the single record context, DATATRIEVE may insert a record in the wrong 
place. the record may not be moved, or you may receive an error message. Once 
you have established a single record context, you can use this context to store 
many records without providing new single record context each time. 


The following example stores a new parts record in the PART S domain and con- 
nects it to a specific occurrence of the CLASS PART set. PART S is an auto- 
matic member of the set CLASS PART, shown in Figure 14-6. You: 


e Establish a-single-record context for the record before you store the record 


e Store the record using the DATATRIEVE CURRENCY clause 


14-38 Using DATATRIEVE with DBMS 


CLASSES 


CLASS_PART <——a_—= Set name 


PART_S 


MK-01599-00 


igure 14-6: DBMS Set CLASS PART 


no Fe 


[R> 
[R> 
[R> 
st: 


Ready the PART S and CLASSES domains for WRITE access. 


Use SHOW SETS to see that PART S is an automatic member of the set 
CLASS PART and that CLASS PART is owned by another domain, 
CLASSES. 


Establish a context with the single-set occurrence of the set CLASS PART 
with which you want to connect the new part record. 


You do this by using the FIND and SELECT statements to establish a 
single-record occurrence of the domain CLASSES with the class code of 
BR. When you select the record in the domain CLASSES, you establish 
context with the correct occurrence of the set CLASS PART. 


Store the new record in the PART S domain and connect it to the current 
occurrence of the CLASS PART set. DATATRIEVE prompts you for data 
values for the new record. 


Check the new record. Because the CLASSES record BR is still the 
selected record, you can use the PRINT statement with the MEMBER 
clause of the record selection expression to see if the GUDGEON record is 
now a member of the class BR. 


READY PART_S WRITE, CLASSES WRITE GZ invetediovnvad (1) 
SHOW SETS Pe a (2) 
CLASS_PART 


Owner: CLASSES 
Member: PART_S, automatic mandatory 


(continued on next page) 
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DTR> FIND BR IN_CLASSES WITH CLASS_CODE = "BR" < nnnnnnee (3) 
[1 record foun 


DIR> SELECT 
DTR> 


DTR> STORE PART_S CURRENCY BR.CLASS_PART Serres (4) 
Enter PART_ID: BR902334 

Enter PART_DESC: GUDGEON 

Enter PART_STATUS: & 

Enter PART_PRICE: 902.00 

Enter PART_COST: 231.00 

Enter PART_SUPPORT: x 

DTR> 


DTR> PRINT PART_ID, PART_DESC OF PART_S MEMBER <coneceren (5) 
[Looking for set name] 


CON> CLASS_PART 


Part 
NOQNOEE.. “Hester Sates en Part Description---------------- 


BR-1234-56 LA34 
BR-3467-91 LA120 
BR-8901-23 LA36 
BR-9023-34 GUDGEON 


DTR> 


Note that you use the CURRENCY clause of the STORE statement to specify 
the exact set occurrence to which DATATRIEVE should connect the record. Note 
that the record being stored with a CURRENCY clause must be an automatic 
member of the set. 


14.10.1.2 Manual Insertion -- If a newly stored record is a manual member of a 
set, you must use the CONNECT statement to insert the record into the set. 
(You can also leave the record unconnected to any set.) You must establish the 
context when you connect the record to the set. 


The following example connects an EMPLOYEE record to a DIVISIONS set. 
Because EMPLOYEES is a manual member of the set CONSISTS OF, you must 
specifically insert the new employee record in the set CONSISTS_ OF. 


1. Ready both the EMPLOYEES and DIVISIONS domains for WRITE 
access. 


2. Store the new employee record. (DBMS automatically connects the record 
of the new employee to the system-owned set, ALL EMPLOYEES, and to 
the sets owned by the employee record, MANAGES and 
RESPONSIBLE FOR.) 


3. Specify each record in the DIVISIONS domain to which you want to con- 
nect the new employee record. Specify the context variable DIV, so you can 
use it later to qualify the set name. 
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4. Specify the new employee record you stored in step 2. 


5. Use the CONNECT statement to connect the new employee record to the 
SOFTWARE division through the set CONSISTS OF. 


6. Print the employees from the set occurrence to see that you made the cor- 
rect set connection. 


IR> READY EMPLOYEES WRITE, DIVISIONS WRITE < ----+--- (1) 


ITR> STORE EMPLOYEES _.. a ane (2) 
ater EMP_ID: 53456 

ater EMP_LAST_NAME: JANOV 

iter EMP_FIRST_NAME: LESLEY 

iter EMP_PHONE: 5324 

iter EMP_LOC: AS 


[R> FOR DIV IN DIVISIONS WITH DIV_NAME = "SOFTWARE" <----- (3) 
JN> FOR EMP IN EMPLOYEES WITH : 


)N> EMP_LAST_NAME = "JANOV" <----- (4) 
)N> BEGIN 

yN> CONNECT EMP TO DIV.CONSISTS_OF ee. (5) 
)N> PRINT EMP_LAST_NAME OF EMPLOYEES MEMBER pitted (6) 
}N> DIV.CONSISTS_OF 

JN> END 

ist Name------ 

JTCHINGS 

\COBONE 

ISCAL 

\NOV 

"R> 


ote that you connect the employee named JANOV to the occurrence of the 

IVISIONS domain (DIV) through the set CONSISTS OF. Where the record is 
serted into the set depends on the set-ordering criteria defined in the schema. 
se the VAX DBMS Database Design Guide for more information on set order. 


1.10.2 Erasing, Disconnecting, and Reconnecting Records with Sets 


ou use the ERASE statement to remove a record. Because the ERASE state- 
ent can delete more than you intend, use it with caution. Accidental deletions 
mn occur because of the ERASE statement’s “cascading effect.” This cascading 
fect can happen whenever the erased record is the owner of a set. Thus, if the 
irrent record is an owner of a set type, ERASE deletes all of the following: 


The current record 
All records in sets owned by the current record 


Any records in sets owned by those members. and so forth 
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You can remove a record from a set either by erasing it with the DATATRIEVE 
ERASE statement or disconnecting and reconnecting it with sets. 


The removal characteristics of a record determine the way in which records can be 
removed from sets, and whether they can be removed from sets. The removal 
characteristic of a record is one of the following: 


° Fixed 


You cannot disconnect the record from its set occurrence unless you erase | 
the record from the database. 


¢ Mandatory 


You cannot use DISCONNECT to remove the record from a set occurrence. 
However. you can use RECONNECT to move it from one occurrence of the 
set type to another. 


e Optional 


You can use either DISCONNECT or RECONNECT to remove the record 
from a set occurrence. 


The following sections discuss removal from a set in more detail. 


14.10.2.1 Erasing DBMS Records -- Records that are fixed members of sets, 
once connected to a set occurrence, must be a member of that specific set occur- 
rence until they are deleted from the database. They cannot be disconnected and 
remain in the database or reconnected to some other set occurrence. 


The fixed characteristic is very common with system-owned sets that are used to 
keep large numbers of records on file. For example, an organization usually keeps 
a generalized listing of all employees. Such a listing can be maintained by a 
system-owned set. as in the PARTS database with the ALL EMPLOYEES set. 


In a previous example, you added the record of the employee named JANOV to 
the ALL EMPLOYEES set and connected it to the SOFTWARE division. The 
following example erases the record JANOV from the database, deleting it from 
the system-owned ALL EMPLOYEES set. As a result of being erased, the recorc 
in the example is also disconnected from the SOFTWARE Group: 


1. Erasing the record for JANOV from the database involves the domains 
EMPLOYEES, DIVISIONS, and PART S. Ready for WRITE access all 
domains that are affected by the loss of an employee. 


If you do not ready all necessary domains, you might encounter a problem 
when you attempt to erase the record. Realms are ultimately associated 
with storage areas, unless the files themselves are readied through a 
READY command that readies at least one of the domains in that file. 
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Therefore, you might receive an error from DBMS stating that a particular 
storage area has not been readied. 


2. Find and select the record you want to erase. 


If the record you erase is the owner of any sets (EMPLOYEES is owner of 
the sets RESPONSIBLE FOR and MANAGES), records in member 
domains (PART S and DIVISIONS) are also erased. Therefore. be sure that 
you know exactly what you are erasing. Table 14-1 summarizes the effects 
of erasing a record on the record and its members. 


3. Make sure that this is the record you want to erase and then erase the 
record. 


4. Show that DATATRIEVE prints nothing in response to the PRINT 
CURRENT statement. The current collection is now empty. 


5. Try to find the record you erased. 


TR> READY EMPLOYEES WRITE, DIVISIONS WRITE, Cl nvecenece (1) 
ON> PART_S WRITE 

TR> Se 

TR> FIND EMPLOYEES WITH EMP_LAST_NAME = "JANOV" < --------- (2) 
1 record found] 

TR> SELECT;PRINT EMP_LAST_NAME CS Aawiicue (3) 
ast Name----------~- 

ANOV 

TR> ERASE 

TR> PRINT CURRENT Penn (4) 
TR> 

TR> FIND EMPLOYEES WITH EMP_LAST_NAME = "JANOV" << --------- (5) 
2 records found] 

TR> 


he employee named JANOV is no longer in the database. As a result of being 
rased, his employee record has also been disconnected from all the sets of which 
was a member. 


4.10.2.2 Disconnecting and Reconnecting DBMS Records from Sets -- 
ecords that are mandatory members of sets can move from one occurrence of 
set to another. However, records with mandatory membership in a set must 
ways be members of some occurrence of that set type once they have been 
mnected. 


he advantage of such membership is the ability to change your mind about the 
‘tributes of a member record. 
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For example, suppose your inventory supervisor wants to move a part record (ter- 
minal stands) from one class of the demain CLASSES (terminal assemblies) to 
another class in that same domain (video terminals). The PART S domain, which 
contains the parts record, is a mandatory member of the set CLASS PART. 


In the following example, you use the set CLASS PART. 


1. 


Ready the necessary domains. Because you are disconnecting a PART S 
record from an occurrence of CLASSES and then connecting it to another 
occurrence, you must ready both those domains for MODIFY access. 


Display the PART S records that contain the letters BU in their PART ID 
number. You want to move the last two parts (the terminal tables for the 
VT52 and VT100) to the occurrence of CLASS PART owned by BT. 


For these two part records, show that they are connected to the particular 
occurrence of the set CLASS PART that is owned by CLASSES record 
BU. Those two records belong to the class called TERMINAL 
ASSEMBLIES. 


Now, determine where you would like to move these two records. First, find 
and display all the PART S records that contain the letters BT in their 
PART ID. 


Then, using a FOR loop, find and display the record occurrence of the 
domain CLASSES to which these two records are related. This is the 
record occurrence, VIDEO TERMINALS, to which you want to reconnect 
your two terminal tables. 


Create the necessary context to reconnect the terminal tables to the video 
terminal set. Use nested FOR loops to create the context and a 
RECONNECT statement to move the records. 


Make sure that you actually moved the records. Find and select the 
CLASSES record with the value BT for CODE. 


DTR> READY PART_S MODIFY, CLASSES MODIFY K roronesccrnsne (1) 


DTR> FIND PART_S WITH PART_ID CONT "BU" veneer ne neeeee (2) 
{7 records found] 
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TR> PRINT PART_ID, PART_DESC OF CURRENT 


Part 
NUNDES, jot ree arenes Ser Part Description-----------~------ 


U-1045-68 FREE-STANDING FRAME ASSEMBLY 
U-2345-67 VIDEO TUBE 

U-3161-25 VT100 NUMERIC KEYPAD ASSY 
U-7014-68 VT100 MONITOR UNIT 

U-7014-65 VT100 KEYBOARD UNIT 
U-3456-70 TERMINAL TABLE VT100 
J-0345-67 TERMINAL TABLE VT52 


IR> FOR PART_S WITH PART_ID CONT "BU345670", < caresecens (3) 


JN> "BUO34567" PRINT CLASSES WITHIN CLASS_PART 
ode -Class Description-- St 


3U TERMINAL ASSEMBLIES Y 


[R> FIND VIDEO_TERMS IN PART_S WITH PART_ID CONT "BT" < onnonnee (4) 


2 records found] 
[R> PRINT PART_ID, PART_DESC OF VIDEO_TERMS 


Part 
Nunber” ‘ AarsssaSssser aes Part Description---~--~---------- 


'-1634-56 VT100 
'-0456-78 VT52 


‘R> FOR VIDEO_TERMS PRINT CLASSES WITHIN CLASS_PART me meneasae (5) 
ide -Class Description-~- St 
iT VIDEO TERMINALS G 
iT VIDEO TERMINALS G 
‘R> FOR VT IN CLASSES WITH CODE = "BT" RK eaberstee (6) 


IN> FOR TABLES IN PART_S WITH PART_ID = "BU345670" OR 
IN> PART_ID = "BU034567" RECONNECT TABLES TO VT.CLASS_PART 
R> 


R> FIND CLASSES WITH CODE = "BT" etigebesecedowacseasey (7) 
record found] 

R> SELECT 

R> PRINT PART_ID, PART_DESC OF PART_S MEMBER OF CLASS_PART 
Part 

Number. “Steerer =s<ereeses Part Description----------------- 


~0456-78 VT52 

-1634-56 VT100 

-0345-67 TERMINAL TABLE VT52 
-3456-70 TERMINAL TABLE VT100 


R> 
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Note that the terminal tables are now members of a new set occurrence. Check 
the former location of those records to make sure they are no longer there: 


DTR> FIND CLASSES WITH CLASS_CODE = "BU" 
[1 record found] 

DTR> SELECT 

DTR> PRINT CURRENT 


Code -Class Description-- St 
BU TERMINAL ASSEMBLIES Y 
DTR> PRINT PART_ID, PART_DESC OF PART_S MEMBER CLASS_PART 


Part 
Number = -~--- 7777377 r Part Description===s2s-"ss"S=--+¢ 


BU-1045-68 FREE-STANDING FRAME ASSEMBLY 
BU-2345-67 VIDEO TUBE 

BU-3161-25 VT100 NUMERIC KEYPAD ASSY 
BU-7014-65 VT100 KEYBOARD UNIT 
BU-7014-68 VT100 MONITOR UNIT 

DTR> 


The terminal tables are no longer in the occurrence of CLASS PART owned by 
BU. 


14.10.2.3 Disconnecting and Connecting DBMS Records from Sets -- 
Records that are optional members of sets can belong to an occurrence of a set 
type or not belong to any occurrence at all. For example, the PARTS database 
has two system sets, ALL PARTS and ALL PARTS ACTIVE. The ALL PARTS 
set describes all parts cataloged by a firm. The ALL PARTS. ACTIVE set con- 
sists of all parts currently in production or inventory. As a part is retired. it may 
be removed from the ALL PARTS ACTIVE set but retained in the ALL PARTS 
listing of everything ever made. 


You can use the DISCONNECT statement to remove OPTIONAL members of 
sets from those sets. You can later use the CONNECT statement to insert the 
disconnected record into another occurrence of the same set type or you can let 
that record remain disconnected in the database. 


The following example disconnects a part from the ALL PARTS ACTIVE set: 


1. Ready the necessary domains. Because you are removing a PART. S recorc 
from a system-owned set, you need only ready PART S for WRITE access. 
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2. Display the record that you want to remove from the 
ALL PARTS ACTIVE set. 

Because ALL PARTS ACTIVE is a system-owned set, you do not have to 
establish context with the SELECT statement when you want to display 
the members of the set. 

3. Establish the context you need to disconnnect a record by specifying in a 
FOR loop the record you want removed from the set. Then use the 
DISCONNECT statement to remove it. 

1. Check the ALL PARTS ACTIVE set to make sure the record is no 
longer there. DATATRIEVE responds with the DTR> prompt rather than 
a display of the record; the part record is no longer a member of the 
ALL PARTS ACTIVE set. 

[R> READY PART_S WRITE RU sesmenaoseese (1) 

[R> 

'"R> PRINT PART_S MEMBER ALL_PARTS_ACTIVE WITH < onrreee (2) 

IN> PART_ID = "BU104568" 

Part Unit 
Numbey 2c s2ese= Part Description-~---------- ST Price 

J-1045-68 FREE-STANDING FRAME ASSEMBLY G $305 

‘R> FOR P IN PART_S WITH PART_ID = "BU104568" i sestese (3) 

IN> DISCONNECT P FROM ALL_PARTS_ACTIVE 

R> 

‘R> PRINT PART_S MEMBER ALL_PARTS_ACTIVE WITH 
IN> PART_ID = "BU104568" ate (4) 
R> 


1.10.3 Summary of Membership Characteristics 


1e record membership criteria limit the changes you can make to a database. 
ible 14-1 summarizes the effects of various statements on the record being 
odified. 
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Table 14-1: Insertion, Retention, and Database Operations 


Effect on Target Record Effect on Member 


CONNECT DISCONNECT Ee MODIFY RECONNECT STORE ERASE 

ALL 

AUTOMATIC Not Possible | Not Allowed Erase Reorder Not Allowed Insert Erase 

FIXED 

AUTOMATIC Not Possible | Not Allowed | Erase Reorder Move Insert Erase 

MANDATORY Reorder 

AUTOMATIC Insert Remove Erase Reorder Move Insert Erase 

OPTIONAL -Reorder 

MANUAL Insert Not Allowed Erase Reorder Not Allowed No Effect 

FIXED : 

MANUAL Insert Not Allowed Erase Reorder Move No Effect Erase 

MANDATORY Reorder 

MANUAL Insert Remove Erase Reorder Move No Effect Erase 

OPTIONAL Reorder 
















INSERTION 
RETENTION 





Not Alloy 





Remove 









Not Allo 









Notes to Table ; Reorder 
Insert : F fps 
: Can affect set ordering. Can cause reordering within ; 
Connects a record into an occurrence of the given set type. set occurrence. 
Move No Effect 
Reconnects a record from one occurrence of the given set Does not affect set membership. 
type to another occurrence of the same set type. This opera- 
tion is equivalent to “Remove” followed by “Insert.” Not Allowed 
Remove . Returns an exception. 
Disconnects a record from an occurrence of the given set Not Possible 
type. Cannot be done. 
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14.10.4 Writing Changes to the Database 


To write the changes you made to the database, you must enter a COMMIT 
statement. If, however, you do not want to save the changes you made. you can 
enter a ROLLBACK statement and leave the database as it was. The following 
statement rolls back any changes: 


DTR> ROLLBACK 
co executed; collection CURRENT automatically released 
R> 


DATATRIEVE automatically readies database domains again after you have con 
mitted or rolled back. 


¢ ACOMMIT statement performs a DBMS COMMIT RETAINING. 
¢ A ROLLBACK statement is equivalent toa DATATRIEVE ABORT. 


The DATATRIEVE FINISH and EXIT commands end access to domains or 
DBMS records. The FINISH command executes a DBMS COMMIT (without th 
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ETAINING argument) when you finish the last readied domain or record, or 
nish them all at once. The EXIT command also executes a DBMS COMMIT 
atement. 


Note — 


There is an important difference between the DATATRIEVE EXIT 
command and the DBQ EXIT command: the DATATRIEVE EXIT 
command executes a DBMS COMMIT statement; the DBQ EXIT com- 
mand issues a DBMS ROLLBACK. 


) write changes to the database, end access to the domains or DBMS records, 
id remain in DATATRIEVE, use the FINISH command. To write changes to 
e database and end your DATATRIEVE session as well as access to domains 
id records, use the EXIT command: 


R> FINISH 
R> EXIT 


1.11 Optimizing Performance 


hen using DATATRIEVE to work with DBMS databases, keep in mind the fol- 
wing considerations: 


Unless you specify otherwise, DATATRIEVE always starts reading database 
areas at page one, line one. DBMS is designed to optimize access paths to 
records through set chain pointers, indexes, and hashing algorithms. Use a 
set name whenever possible to optimize your database access paths and pre- 
vent sequential reads of database areas. 


‘To minimize record locking, be sure to issue COMMIT or ROLLBACK state- 
ments regularly to explicitly end database transactions. Locks prevent other 
users from accessing a record and can prevent access to other records 
because that record contains pointer information that also gets locked. 
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‘ou can use VAX DATATRIEVE to access VAX Rdb databases. the DIGITAL 
imily of relational database management systems. Rdb provides the advantages 
f a database management system, including data security and integrity. At the 
ame time, its relational model of data organization is easier to understand and to 
se than the network (CODASYL-style) model of data organization. 


\IATATRIEVE alone provides excellent data access when your database contains 
»wer than 5000 records. If your database is larger than that, using Rdb for data 
sorage optimizes response time for your DATATRIEVE queries, data mainten- 
nee, and report-writing tasks. 


he DATATRIEVE statements you use for data queries and report writing are 
ve same, whether you are accessing a file-structured database or an Rdb one. 
‘you currently use DATATRIEVE to create and maintain file-structured 
atabases, you need to learn some extensions to the DATATRIEVE language to 
scess and maintain an Rdb database. 


5.1 Getting Started with DATATRIEVE and Rdb 


1 an Rdb database, data is organized into relations. Relations are simply tables. 
table has a horizontal dimension (rows) and a vertical dimension (columns). A 
w in a relation is a set of data fields, analogous to a record in a file. The fields in 
ich row define the columns. In this chapter, the term record refers to an entire 
w in a database relation. Figure 15-1 shows part of the structure of a relation 
Uwled DEPARTMENTS in the PERSONNEL database installed with the 
ATATRIEVE UETP (User Environment Test Package). 


igure 15-2 shows the relations and fields for the sample PERSONNEL 
itabase. Examples in this chapter refer to the relation and field names in the 
ERSONNEL database. The data shown in the examples may be different than 
\e data that appears on your screen. 


15-1 










Row 1 ———» 
Row 2 ———_» 
Row 3 ———» 
Row 4 ———» 
Row 5 ————» 


‘Column 1 Column 2 ; Column 3 
DEPARTMENT_CODE | DEPARTMENT_NAME MANAGER_ID 


ADMN 


Engineering 


Figure 15-1: Sample Rdb Relation 


EMPLOYEES 





EMPLOYEE_ID 
LAST_NAME 
FIRST_NAME 
MIDDLE_INITIAL 
ADDRESS_DATA 
STREET 

TOWN 

STATE 

ZIP 

SEX 

BIRTHDAY. 
SOCIAL_SECURITY 
STATUS_CODE 


SALARY—HISTORY 


EMPLOYEE_ID 
SALARY AMOUNT 
SALARY—START 
SALARY_END 


DEGREES 


EMPLOYEE_ID 
COLLEGE_CODE 
YEAR-GIVEN 
DEGREE 
DEGREE_FIELD 


JOB_HISTORY 


EMPLOYEE_ID 
DEPARTMENT—CODE 
JOB_CODE 
JOB_START 
JOB_END 
SUPERVISOR-_ID 


DEPARTMENTS 


DEPARTMENT—CODE 
DEPARTMENT_NAME 
MANAGER-_ID 
BUDGET_PROJECTED 
BUDGET_ACTUAL 


Figure 15-2: Sample Rdb Database 
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Corporate Administration 
Electronics Engineering 
Large Systems Engineering 
Mechanical Engineering 
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JOBS 


JOB_~CODE 
WAGE_CLASS 
JOB_TITLE 
MINIMUM_SALARY 
MAXIMUM_SALARY 


COLLEGES 
COLLEGE_CODE 


COLLEGE—NAME 
ADDRESS_DATA 


WORK_STATUS 
STATUS_CODE 


STATUS_NAME 
STATUS_TYPE 


MK-01601-00 


he following command sets the CDD default to the directory that contains the 
atabase definition and the domain definitions used in this chapter. 


(R> SET DICTIONARY CDD$TOP .DTR$LIB.DEMO.RDB 


he examples and references in this chapter refer to Rdb/VMS. DATATRIEVE 
yes, however, support the family of Rdb relational database products. For exam- 
es of using DATATRIEVE with Rdb/ELN, see the documentation for that 
‘oduct. 


5.2 Creating a Path Name for the Database 


ou must use an interactive Rdb utility, RDO in Rdb/VMS, to define your Rdb 
itabase. The VAX Rdb/VMS Guide to Database Design and Definition tells you 
yw to do this for an Rdb/VMS database. 


define an Rdb/ELN database, use the data definition language compiler for 
db/ELN. The VAX Rdb/ELN Application Development Guide tells you how to 
) this. 


) access an Rdb/VMS database with DATATRIEVE, it must have a CDD path 
ime. A path name may be specified when an Rdb database is created. If the Rdb 
itabase you want to access with DATATRIEVE already has a path name, you 

n use that path name to access the database. 


you want to access an Rdb database that does not have a path name, you can > 
eate a path name with the DATATRIEVE DEFINE DATABASE command: 


=FINE DATABASE Rdb-database-path ON root-file-spec; 
jJb-database-path 

the path name you want to assign the database. 
ot-file-spec 

the file specification of the database file. 


1e following examples illustrate three valid commands to establish a path name 
¢ the PERSONNEL database: 


R> DEFINE DATABASE , CDD$TOP .DEPT29.PERSONNEL ON 


ise DBA2: [D29.DAT]PERSONNEL . RDB; 
> 


R> DEFINE DATABASE CDD$TOP.DTR$LIB.DEMO.RDB.PERSONNEL 
N> ON DTR$LIBRARY: PERSONNEL; 
R> 


R> DEFINE DATABASE PERSONNEL ON PERSONNEL; 
R> 
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The first two examples specify full path names and file specifications for the 
databases. The third example relies entirely on current defaults, both for the 
path name and the file specification. 


Because VAX Rdb/ELN does not use the CDD, you must issue a DATATRIEVE 
DEFINE DATABASE command to establish a path name for the Rdb/ELN 
database. 

15.3 Accessing the Database 

After you create a path name for your Rdb database, you can access it with 
DATATRIEVE in either of two ways: 

e Ready the database directly. 


e Define a domain for each Rdb relation that you want to access, and then 
ready the domains you want to use. 


15.3.1. Readying an Rdb Database Directly 


Using the following syntax, you can ready an Rdb database without defining 
DATATRIEVE domains for any relations: 


READY database-path-name 


[SNAPSHOT] 
PROTECTED READ 
SHARED WRITE 
EXCLUSIVE MODIFY 

EXTEND 


USING rdb-relation-name [AS alias] 
dbms-record-name 


[SNAPSHOT] 
Le] 
PROTECTED READ 
SHARED WRITE 
EXCLUSIVE MODIFY 
EXTEND 
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latabase-path-name 

s the CDD path name of the Rdb database. 

iccess mode 

s the method (SNAPSHOT, PROTECTED, SHARED, or EXCLUSIVE) by 
deat you access the data. In Rdb, SNAPSHOT or read-only, is the default access 


ccess option 


s the option (READ, WRITE, MODIFY, or EXTEND) by which you access the 
tdb data. , 


ISING clause 


imits access to specified relations. If you omit the USING clause of the READY 
JATABASE command. all relations in the database are readied. 


slation-name 

; the name usec in the Rdb utility te define the relation. 

lias © 

; a name you use to refer to the relation specified. If you include an alias, you 
lust use it in all the DATATRIEVE statements and commands that refer to the 


2adied relation. 


he following examples illustrate various ways to ready a database directly. 


eady an entire database: 


[R> READY PERSONNEL 
[R> 


[R> READY CDD$TOP.DEPT39.PERSONNEL MODIFY 
[R> 


eady selected relations: 


"R> READY CDD$TOP.DEPT39.PERSONNEL USING EMPLOYEES 
*R> 


"R> READY PERSONNEL USING EMPLOYEES, SALARY_HISTORY WRITE 
"R> 
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The results of the READY command are discussed in Section 15.3.3 of this 
chapter. 


15.3.2 Defining and Readying Rdb Domains 


You can define a DATATRIEVE domain for each Rdb relation that you want to 
access. Then, you use the domain names to ready the database relations you want 
to access. . 


Accessing your database through domains slows DATATRIEVE performance; 
accessing a database directly works more quickly. However, you may want to 
define domains because: 


® You can define DATATRIEVE view domains of Rdb relations 


e You can link a form definition with a domain definition using the FORM IS 
syntax 


You can use the DISPLAY FORM statement to link a form with a relation that is 
not defined as a domain. However, if you want the relation to display data auto- 
matically on a form, you must create a domain definition and include the FORM 
IS clause: 


DEFINE DOMAIN domain-name [USING] relation-name 
[OF [DATABASE]] database-path 
[FORM [IS] form-name [IN] form-library]; 


domain-name 


Is the name you want for the domain. It can be the same as the relation name, but 
it does not have to be the same. 


relation-name 

Is the name used to define the relation in the Rdb database. 
database-path 

Is the CDD path name of your Rdb database. 

form-name 

Is the name given the form when it was created. 
form-library 


Is the name of the form library. 
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7or example, the following commands define domains for the EMPLOYEES and 
SALARY HISTORY relations in the PERSONNEL database: 


\TR> DEFINE DOMAIN EMPLOYEES USING EMPLOYEES OF 
IFN> DATABASE CDD$TOP .DTR$LIB.DEMO.RDB.PERSONNEL; 
ITR> 


ITR> DEFINE DOMAIN SALARY_HISTORY USING SALARY_HISTORY OF 
IFN> DATABASE CDD$TOP .DTR$LIB.DEMO.RDB.PERSONNEL 

IFN> FORM IS SALARYHST IN FORMSLIB; 

ITR> 


\fter you define a domain for a relation in an Rdb database. you can ready it. You 
lo not supply a DATATRIEVE definition of the fields and indexes associated 

vith each domain. DATATRIEVE retrieves this information from Rdb when you 
eady the domains: 


TR> READY SALARY_HISTORY, EMPLOYEES 
TR> 


5.3.3 Results of the READY Command 


f you do not specify an access mode or an access option for an Rdb database, Rdb 
omain, or Rdb relation, the default access is SNAPSHOT. Other users can have 
LEAD, WRITE, MODIFY or EXTEND access to the database, domain, or rela- 
ion. The following example shows the result of readying a database directly. 

‘here are no-domains defined for the relations in this example: 


TR> READY PERSONNEL 
TR> SHOW READY 
eady sources: 
WORK_STATUS: Relation, Rdb, snapshot read 
<CDD$TOP . DTR$LIB.DEMO.RDB.PERSONNEL; 1> 
DEGREES: Relation, Rdb, snapshot read 
<CDD$TOP . DTR$LIB.DEMO.RDB.PERSONNEL; 1> 
COLLEGES: Relation, Rdb, snapshot read 
<CDD$TOP . DTR$LIB.DEMO.RDB.PERSONNEL; 1> 
DEPARTMENTS: Relation, Rdb, snapshot read 
<CDD$TOP . DTR$LIB.DEMO.RDB.PERSONNEL; 1> 
JOBS: Relation, Rdb, snapshot read 
<CDD$TOP . DTR$LIB.DEMO.RDB.PERSONNEL; 1> 
SALARY_HISTORY: Relation, Rdb, snapshot read 
<CDD$TOP . DTR$LIB.DEMO.RDB.PERSONNEL; 1> 
JOB_HISTORY: Relation, Rdb, snapshot read 
<CDD$TOP . DTR$LIB .DEMO.RDB.PERSONNEL; 1> 
EMPLOYEES: Relation, Rdb, snapshot read 
- - <CDD$TOP .DTR$LIB.DEMO.RDB.PERSONNEL; 1> 
» loaded tables. 


[R> 
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The default access mode, SNAPSHOT, is called a read-only or “snapshot” ready. 
It lets you read data without locking other users out of the database. In such an 
access mode, you see a “picture” of the database, exactly as it was when you 
readied the relation, domain, or database. Other users can access and change the 
data in the database you have readied. 


You do not see changes other users make until you issue a FINISH, COMMIT, 
ROLLBACK, or another READY command. the relation or database. When you 
use this access mode, there is no write locking of the database. Rdb does place 
read locks in SNAPSHOT mode, however. 


In order to have SNAPSHOT access, you must ready all relations that you want 
to use in a database with SNAPSHOT access. Thus, when you ready a database, 
relation. or domain with SNAPSHOT access, and you also ready one or more rela: 
tions or domains from that database with a more restrictive mode, you actually 
have SHARED READ access rather than SNAPSHOT access to all the domains 
or relations. In SHARED READ mode, DATATRIEVE uses standard read locks 
and you see other users’ modifications as they are committed. 


15.4 Using Views 


A view is a “virtual” relation. Its definition specifies fields from one or more 
source relations. A view contains no data. You cannot always use views for store 
or modify operations, but you can use them to display records. 


You might want to create a view that is a subset of the fields in a relation when 
you do not want certain users to see confidential data. You would give these users 
access to the view, but not to the relation itself. 


You might want to create a view that joins fields from more than one relation 
when you know that users will often request that combination of fields. It is 
simpler for users to access and display the view than it is for them to repeat a 
query that accomplishes the same relational join. 


You can create views using either an Rdb utility (in which case, DATATRIEVE 
treats the relations as any other relations in the Rdb database), or 
DATATRIEVE, or both. 


15.4.1 Using Rdb Views 


You create a view relation using the RDO utility. After you create a view with the 
RDO utility. you can access it with the READY DATABASE command, just as 
you can a simple relation. If you want your view to use a form automatically, 
define a DATATRIEVE domain for it. 
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here are advantages to using Rdb views rather than view domains: 


DATATRIEVE’s response time is faster when you use Rdb views. 


You can store or modify records using Rdb views if they contain fields from 
only one source relation. You cannot store records using DATATRIEVE view 
domains, even when those views access fields from only one relation. 


5.4.2 Defining and Using View Domains 


iew domains provide the following advantages: 


You can create views that combine fields from an Rdb database with fields 
from RMS (file-structured) and DBMS domains. The ability to combine fields 
from different types of databases is a powerful feature of DATATRIEVE 
view domains. 


Your installation might decide that creating an Rdb view does not benefit 
enough database users to warrant creating one. In this case, you can ‘create a 
DATATRIEVE view that benefits you personally. 


You can refer to DATATRIEVE domain tables with a view domain. This 
allows you to establish constraints that are not defined for the Rdb database, 
but that are appropriate for your personal application. 


1 such cases, create a view domain with the DEFINE DOMAIN command. 


EFINE DOMAIN view-path-name OF domain-path-name-1 [....] ie 


level-number-1 field-name-1 © OCCURS FOR rse-1 


OCCURS FOR rse-n 


level-number-2 field-name-2 FROM domain-path-name-n 





[FORM [IS] form-name [IN] form-library] 


Note 


You cannot base view domains directly on relations. You must first 
define a DATATRIEVE domain for each relation the view accesses. 


Using DATATRIEVE with Rdb 15-9 


Refer to the VAX DATATRIEVE Reference Manual for a detailed explanation of 
the arguments and restrictions that apply to view domains. 


The following examples define view domains for the PERSONNEL database. The 
view domain MAILING INFO uses a subset of fields from the EMPLOYEES 
domain: 


DTR> DEFINE DOMAIN MAILING_INFO OF EMPLOYEES 
DFN> 01 NAME_AND_ADDRESS OCCURS FOR EMPLOYEES. 


DFN> 03 FIRST_NAME FROM EMPLOYEES. 
DFN> 03 MIDDLE_INITIAL FROM EMPLOYEES. 
DFN> 03 LAST_NAME FROM EMPLOYEES. 
DFN> 03 ADDRESS_DATA FROM EMPLOYEES. 
DFN> 03 STREET FROM EMPLOYEES. 
DFN> 03 TOWN FROM EMPLOYEES. 
DFN> 03 STATE FROM EMPLOYEES. 
DFN> 03 ZIP FROM EMPLOYEES . 
DFN> FORM IS MAILFORM IN FORMSLIB; 

DTR> 


The view domain MANAGER NAMES uses fields from both the EMPLOYEES 
and DEPARTMENTS domains and a domain table, MANAGERS TABLE, that 
is based on current values in the DEPARTMENTS domain. EMPLOYEE ID is 
defined as a query name for MANAGER ID in the DEPARTMENTS domain. 
MANAGERS TABLE pairs the query name EMPLOYEE ID with the associated 
DEPARTMENT CODE: 


DTR> DEFINE DOMAIN MANAGER_NAMES OF DEPARTMENTS, EMPLOYEES USING 
DTR> 01 DEPARTMENT OCCURS FOR DEPARTMENTS. 

DFN> 03 DEPARTMENT_CODE FROM DEPARTMENTS. 

DFN> 03 DEPARTMENT_NAME FROM DEPARTMENTS. 

DFN> 03 MANAGED_BY OCCURS FOR EMPLOYEES WITH 


DFN> EMPLOYEE_ID IN MANAGERS_TABLE. 
DFN> 06 FIRST_NAME FROM EMPLOYEES. 

DFN> O06 MIDDLE_INITIAL FROM EMPLOYEES. 

DFN> 06 LAST_NAME FROM EMPLOYEES. 

DFN> ; 

DTR> 


You access a view domain by readying it, just as you would a simple domain. 


15.5 Displaying Information About Readied Relations and 
Domains 


The SHOW READY and SHOW FIELDS commands provide information about 
the relations and fields you can access. For example, the following commmands 
ready the domain SALARY HISTORY and show the fields you can access in the 
SALARY HISTORY relation. 
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[R> READY SALARY_HISTORY 
[R> SHOW. READY 
xady sources: 
SALARY_HISTORY: Domain, Rdb, snapshot 
<CDD$TOP . DEPT29 . PERSONNEL. SALARY_HISTORY; 1> 
» loaded tables. 


"R> SHOW FIELDS FOR SALARY_HISTORY 
SALARY_HISTORY 


EMPLOYEE_ID <Number> 
SALARY_AMOUNT <Number> 
SALARY_START <Date> 
SALARY_END <Date> 


‘R> 


5.6 Ending Access to Domains, Relations, and Views 


se the FINISH command to end access to the database or databases, or to 
lected parts of the database: 


ALL 


domain-name 
NISH dbms-record-name [,..-] 
rdb-relation-name 


main-name 
the name of a DATATRIEVE domain or view domain. 
lation-name 


the name of an Rab relation or view relation. 


you do not specify any names in the FINISH command, DATATRIEVE ends 
cess to everything currently readied. 


i.7 Storing and Maintaining Data in an Rdb Database 


vo extensions to the DATATRIEVE language apply only when your data is 
inaged by a database management system. These extensions are the COMMIT 
d ROLLBACK statements. To understand what these statements do, you must 
derstand the way Rdb stores and updates information in your database and 

w this differs from storing and updating information in a file-structured 

tabase. 
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When you ready a file-structured domain, DATATRIEVE opens the data file 
associated with the domain and makes any changes to the data file as you enter 
them. Once the changes are made to the file, you can consider them permanent. 


When you ready an Rdb database directly or when you ready Rdb domains, 
DATATRIEVE makes any changes to the database as you enter them. However, 
those changes are not permanent until one of the following occurs: 


e You enter a COMMIT statement, either interactively or as part of a 
procedure 


¢ You enter a final FINISH statement for the last readied domain or the last 
readied relation (depending upon your chosen method of database access) 


e You exit from DATATRIEVE 


If you decide that you do not want your entries to take effect, you can enter a 
ROLLBACK statement. When you use the ROLLBACK statement. all the 
changes made since execution of the last COMMIT or ROLLBACK statement 
are undone. If neither statement executed, implicitly or explicitly. then the 
ROLLBACK statement undoes all the changes made since the beginning of 
your session. . 


Note that a COMMIT or a ROLLBACK affects all readied databases. 


DATATRIEVE executes an implicit COMMIT statement when you finish your 
last readied domain or relation and when you exit DATATRIEVE. In this case, 
there is no chance of losing your database modifications because you forgot to 
enter COMMIT before you finished all your domains or relations, or before you 
exited DATATRIEVE. 


If your system fails, an implicit ROLLBACK executes. In this case, Rdb undoes 
all changes made to the database since execution of the last COMMIT or 
ROLLBACK statement. If you open a DATATRIEVE log file at the beginning ol 
your session, it is easy to find out what changes need reentry after a system fail- 
ure. On a more sophisticated level, Rdb provides journaling and other facilities 
that help you recover from an accident. In any event, do not rely on reports that 
were generated before the system failure to determine what changes have been 
permanently stored. 


Once you access data (print, store. or modify it) in a domain or relation. you mus 
enter a COMMIT or ROLLBACK before you can ready the domain or relation 
again. If, for instance, you want to change the access mode for a relation, you 
must first issue a COMMIT or ROLLBACK. 
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you are working with more than one domain or relation at a time, finishing 
ne or more, but not all, readied domains or relations has no effect on data 
ermanence. For instance, assume you ready three domains or relations 

JNE DOMAIN, TWO DOMAIN, and THREE DOMAIN) and store data in 
INE DOMAIN. You can finish ONE DOMAIN, but data is not permanently 
tored until you have explicitly finished or committed all the readied domains 
or that database. 


nother way of thinking about COMMIT and ROLLBACK statements is to 
nderstand that they end transactions. When working with Rdb databases, it is 
nportant to think in terms of transactions. Because Rdb gives many users 

ccess to a database at the same time. it controls their activities to avoid access 
mflicts and data inconsistencies. Rdb, therefore, requires each user to identify a 
nit of database activity. called a transaction. 


_transaction is an operation on the database that must complete as a unit or not 
ymplete at all. In DATATRIEVE, a transaction on an Rdb database begins with 
READY command and ends with either a COMMIT, FINISH, or ROLLBACK. 
ransactions cannot be nested; they can only be performed consecutively. 


ecause you cannot selectively commit or rollback some parts of a transaction 
1d not others, it is important to keep transactions short. In addition, you should 
'y to conduct transactions with SHARED access if possible. 


he next two sections discuss the COMMIT and ROLLBACK statements in 
reater detail and present some examples of their use. 


5.7.1 Using the COMMIT Statement 
he format of the COMMIT statement is: 


OMMIT 


‘hen you enter a COMMIT statement, you make permanent all the changes 
ade to the database since execution of the last COMMIT or ROLLBACK state- 
ent and release all locks held during the transaction. If neither of these was 
cecuted since the beginning of your session, entering COMMIT means that you 
ish to make permanent.all the database changes you have made during your 
ATATRIEVE session. 


ote that when you issue a COMMIT statement, it affects all databases that may 
» readied, including other Rdb or DBMS databases. 


1e COMMIT statement maintains all collections of Rdb records. When you issue 
COMMIT statement. Rdb starts a new transaction. The collection will include 
mmitted changes other users make to the records in your collection since you 
rmed the collection. 
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The following examples illustrate explicit and implicit execution of the COMMIT 
statement: . 


= ~—-« Using an explicit COMMIT statement: 


DTR> READY PERSONNEL USING JOB_HISTORY WRITE 
DTR> STORE JOB_HISTORY 

Enter EMPLOYEE_ID: 00166 

Enter JOB_CODE: APGM 

Enter JOB_START: 11-Nov-1979 

Enter JOB_END: 8-Aug-1981 

Enter DEPARTMENT_CODE: PRMG 

Enter SUPERVISOR_ID: 00319 

DTR> COMMIT 


¢ Using the FINISH command (implicit COMMIT): 


DTR> READY PERSONNEL USING JOB_HISTORY WRITE 
DTR> REPEAT 2 STORE JOB_HISTORY 
Enter EMPLOYEE_ID: 00164 

Enter JOB_CODE: DMGR 

Enter JOB_START: 9-Sept-1981 
Enter JOB_END: 18-Feb-1983 
Enter DEPARTMENT_CODE: MBMN 
Enter SUPERVISOR_ID: 00359 
Enter EMPLOYEE_ID: 12487 

Enter JOB_CODE: SPGM 

Enter JOB_START: 07-Jul-1980 
Enter JOB_END: 9-Sep-1981 

Enter DEPARTMENT_CODE: MCBM 
Enter SUPERVISOR_ID: 04164 

DTR> FINISH 


e Exiting from DATATRIEVE (implicit COMMIT): 


DTR> SHOW STORE_JOB_HISTORY 

PROCEDURE STORE_ JOB_HISTORY 

SET ABORT 

READY PERSONNEL USING JOB_HISTORY WRITE 
DECLARE REC_NUM PIC 999. 

REC_NUM = *."number of records you are adding" 
REPEAT REC_NUM STORE JOB_HISTORY 

DTR> : STORE_JOB_HISTORY 

Enter number of records you are adding: 5 
Enter DEPARTMENT_CODE: ELGS 


DTR> EXIT 
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the first example, one record is permanently stored in the relation 
JB HISTORY following the COMMIT statement. 


the second example, the FINISH command does not specify any domain or 
lation name and so ends access to the entire database, not just JOB HISTORY. 
therefore results in an implicit COMMIT statement. In this case, two records 

e permanently stored in JOB HISTORY after the FINISH command. 


the third example. the EXIT command (or CTRL/Z entered at the DTR> 
ompt) implicitly executes a COMMIT statement. The results are the same as in 
e second example, except that five records are permanently stored in 

)B HISTORY. 


Note 


The use of CTRL/Y exits you from DATATRIEVE but signals 
abnormal termination. When you enter CTRL/Y. Rdb executes a 
ROLLBACK command. You receive no message from DATATRIEVE, 
however, to tell you this has been done. 


all these examples, the COMMIT statement could affect previous database 
anges (those entered after execution of a COMMIT or ROLLBACK statement, 
t before the READY commands in the examples). An explicit COMMIT. as in 
e first example. maintains any collections of Rdb records. However, an implicit 
JMMIT. as in the second and third examples, releases collections of Rdb 

cords. 


Note 


It is always better to end a transaction explicitly with a COMMIT or 
ROLLBACK statement than to rely on DATATRIEVE to interpret a 
statement as an implicit end to a transaction. That way, you can be 
sure which operations are included in each transaction. 


.7.2 Using the ROLLBACK Statement 
e format of the ROLLBACK statement is: 


YLLBACK 
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When you enter a ROLLBACK statement, you undo all the changes made to the 
database since execution of the last COMMIT or ROLLBACK statement. If nei- 
ther of these was executed since the beginning of your session, entering 
ROLLBACK means that you wish to undo all the database changes you have 
made during your DATATRIEVE session. 


The ROLLBACK statement releases all collections of Rdb records. 


Note that when you issue a ROLLBACK statement, it affects all readied 
databases, including other Rdb and DBMS databases. 


ROLLBACK has the same effect as an ABORT statement. This means that it ca 
alter the flow of execution of procedures, command files, and nested statements. 


If you make a mistake when entering data for one of the records you are storing, 
you can still use CTRL/Z to keep that record from being stored. When you use 
CTRL/Z in this way, you affect only the record on which you are working, not an 
other record entries you might have made. 


The following examples illustrate the use of the ROLLBACK statement: 


¢ Using the ROLLBACK statement interactively: 


DTR> READY DEPARTMENTS WRITE 

DTR> REPEAT 2 STORE DEPARTMENTS 

Enter DEPARTMENT_CODE: ADMN 

Enter DEPARTMENT_NAME: Corporate Administration 
Enter MANAGER_ID: 00225 

Enter BUDGET_PROJECTED: 50000 

Enter BUDGET_ACTUAL: 52000 

Enter DEPARTMENT_CODE: ELEL 

Enter DEPARTMENT_NAME: Electronics Engineering 
Enter MANAGER_ID: 00397 

Enter BUDGET_PROJECTED: 140000 

Enter BUDGET_ACTUAL: 172000 

DTR> ROLLBACK . 


e Entering an ineffective ROLLBACK statement: 


DTR> READY DEPARTMENTS WRITE 

DTR> REPEAT 2 STORE DEPARTMENTS 

Enter DEPARTMENT_CODE: ELGS 

Enter DEPARTMENT_NAME: Large Systems Engineering 
Enter MANAGER_ID: 00369 

Enter BUDGET_PROJECTED: 75000 

Enter BUDGET_ACTUAL: 72000 

Enter DEPARTMENT_CODE: ELMC 

Enter DEPARTMENT_NAME: Mechanical Engineering 
Enter MANAGER_ID: 00435 

Enter BUDGET_PROJECTED: 42000 

Enter BUDGET_ACTUAL: 42200 

DTR> FINISH 

DTR> ROLLBACK 
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Using the ROLLBACK statement in a procedure: 


DTR> SHOW STORE_DEPARTMENTS 
PROCEDURE STORE_DEPARTMENTS 
SET ABORT 
READY DEPARTMENTS WRITE 
DECLARE REC_NUM PIC 999. 
DECLARE COMM_OR_ROLL PIC X. 
PRINT SKIP 
REC_NUM = *."number of records you are adding" 
DECLARE VALID_ANSWER PIC X. 
VALID_ANSWER = "1" 
SET NO ABORT 
REPEAT REC_NUM STORE DEPARTMENTS 
PRINT SKIP 
COMM_OR_ROLL = *."Y if you want the records stored, N if not" 
WHILE VALID_ANSWER = "i" 
BEGIN 
CHOICE 
COMM_OR_ROLL = "N", "n" THEN 

BEGIN 

PRINT SKIP, "The record(s) you added will be deleted." 

VALID_ANSWER = "0" 

ROLLBACK 


END 
‘COMM_OR_ROLL = "Y", "“y" THEN 
BEGIN 
PRINT SKIP, "The record(s) you added will be permanently stored." 
VALID_ANSWER = "0" 
COMMIT 
END 
ELSE 
BEGIN 
PRINT SKIP, "Try again....", SKIP 
Spinone = «."Y if you want the records stored, N if not" 
EN 
END_CHOICE 
END 
FINISH DEPARTMENTS 
PRINT SKIP, "End of access to DEPARTMENTS." 
END_PROCEDURE 


DTR> :STORE_DEPARTMENTS 


Enter number of records you are adding: 5 
Enter DEPARTMENT_CODE: MBMF 


Enter Y if you want these records stored, N if you don’t: N 
The record(s) you added will be deleted. 
End of access to DEPARTMENTS. 


DTR> 
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In the first example, the ROLLBACK statement means that two records are 
stored in the database, then deleted. A ROLLBACK statement could also undo 
changes to the database that were entered prior to either STORE statement 
entry and not noted in this example. 


In the second example, a FINISH command that ends access to all readied 
domains immediately precedes the ROLLBACK statement. Because that FINISH 
command implicitly executes a COMMIT statement, the two records are perma- 
nently stored. ROLLBACK does not do what the user intended. 


In the third example, the ROLLBACK statement means that all of the records 
stored when the REPEAT statement executes are deleted. If the user enters all 
five records, then those five records are deleted. If the user enters CTRL/Z while 
storing data for one of the records. then execution of the REPEAT statement 
stops. The rollback affects. however, many records that have been entered, plus 
any other database modifications made since execution of the last COMMIT or 
ROLLBACK statement or since the beginning of the DATATRIEVE session. 


Note placement of the SET [NO] ABORT statements in the procedure. If the 
SET ABORT statement were not in effect. the displays for storing records would 
appear whether or not WRITE access to the domain or relation were secured. If 
the SET NO ABORT statement were not in effect, the domain or relation would 
not be finished. Because the ROLLBACK statement has the same effect as an 
ABORT statement, the Assignment and PRINT statements associated with the 
rollback branch of the procedure precede the ROLLBACK statement itself. 


If you are designing procedures to be used by people unfamiliar with 
DATATRIEVE, you probably want to include the FINISH command in your pro- 
cedure, particularly if a domain or relation has been readied for protected WRITE 
access. Otherwise, the domain or relation remains locked to all users after your 
procedure executes. If your procedure includes a ROLLBACK option, however, 
make sure that the FINISH statement does not execute before the ROLLBACK 
statement. Otherwise, if the FINISH statement ends user access to the last 
readied domain (or to all of them at once), a COMMIT statement executes before 
the ROLLBACK statement does. 


15.8 Querying the Database, Writing Reports, and Using 
Collections 


The statements you use for queries and report writing are the same for Rdb rela- 
tions or domains as they are for other domains. 
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Tere are some reminders if you plan to use collections: 


A COMMIT statement maintains collections of records. (Note, however, that 
if you ready the source [domain, relation, or database] for that collection with 
a different access mode, the collection i is not maintained). 


The ROLLBACK statement releases any collections that contain Rdb 
records. 


The FINISH statement releases any soliections containing records from the 
domain. relation, or database being finished. 


fake sure you ready domains, relations, or the database with the access you need 
or the collections you plan to create. If you inadvertently ready the database for 
LEAD access, form a large collection, print some records, and then try to modify 
ecords, you get an error message. At this point, you must enter COMMIT before 
ou can‘ready the database for MODIFY access. 


Vhen designing procedures that produce reports or displays that include database 
hanges, remember to enter a COMMIT statement before the PRINT or 

-EPORT statement. Otherwise, in the event of a rollback, your report or display 
‘ill include data changes that were subsequently deleted from the database. 
imilarly, any query based on assumed database modifications should be preceded 
y a COMMIT statement. 


5.9 Using Rdb’s Segmented String Data Type in 
DATATRIEVE 


'‘ATATRIEVE provides limited support for a special Rdb data type called 
ogmented string. 


ields defined with the segmented string data type can contain completely 
astructured data. Segmented string fields have these special characteristics: 


You can store any type of data in a segmented string field. Segmented 
strings can contain ASCII text, binary code, Remote Graphics Instruction 
Set (ReGIS) graphics, or any other data type. 


You do not have to specify the length of data in a segmented ‘string. This 
makes segmented strings useful for storing data that is arbitrarily long, such 
as text files or graphic data. 


Rdb does not allocate any storage space for segmented string fields unless 
you actually store data in the field. This makes segmented string fields a 
good choice for optional comments or descriptions associated with a record. 
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Using DATATRIEVE, you can display, modify, and store data in segmented 
string fields. 


The remainder of this section describes: 


¢ Defining segmented string fields in Rdb 
e Displaying segmented string fields in DATATRIEVE 
e Storing and modifying segmented string fields in DATATRIEVE 


e« Restrictions and usage notes 


15.9.1. Defining Segmented String Fields in Rdb 


You cannot use DATATRIEVE to define segmented string fields. To define seg- 
mented string fields. use Rdb’s RDO utility. 


The following example shows how to use RDO to define a segmented string field 
and a relation that uses it. Once defined, you can use the relation as part of the 
sample Rdb database. PERSONNEL, created during installation of 
DATATRIEVE. 


The segmented string field RESUME contains the resume for an employee in the 
PERSONNEL database. The EMPLOYEE ID field links the RESUME relations 
with other relations in the PERSONNEL database. 


$ RUN SYS$SYSTEM: RDO 
RDO> SET DICTIONARY CDD$TOP .DTR$LIB.DEMO.RDB 
RDO> ! First invoke the sample PERSONNEL database: 
RDO> INVOKE DATABASE PATHNAME PERSONNEL 
RDO> ! Define a segmented string field called RESUME: 
RDO> DEFINE FIELD RESUME 
cont> DATATYPE IS SEGMENTED STRING. 
RDO> ! Define a relation using RESUME and EMPLOYEE_ID, which is based 
RDO> ! on an already-defined field, ID_NUMBER: 
RDO> DEFINE RELATION RESUMES. 
cont> EMPLOYEE_ID 
cont> — BASED ON ID_NUMBER. 
cont> RESUME. 
cont> END RESUMES RELATION. 
RDO> ! Display the fields for the relation RESUMES: 
RDO> SHOW FIELDS FOR RESUMES 
Fields for relation RESUMES 


EMPLOYEE_ID text size is 5 
“based on global field ID_NUMBER 
RESUME segmented string 


segment_length 512 
RDO> ! Use the COMMIT statement to store the 
RDO> ! new field and relation for PERSONNEL: 
RDO> COMMIT 
RDO> EXIT 


15-20 Using DATATRIEVE with Rdb 


15.9.2 Displaying Segmented String Fields in DATATRIEVE 


Co display data in segmented string fields from within DATATRIEVE, follow 
these steps: 


» Ready the database. For best performance, use only the relations that you 
need to work with (in this example, the RESUMES relation defined in the 
preceding section). 


' Use DATATRIEVE PRINT or LIST statements to display data in the seg- 
mented string field. 


“he following example illustrates these steps: 


TR> SET DICTIONARY CDD$TOP.DTR$LIB.DEMO.RDB 
TR> SHOW DATABASES 
atabases: 

PERSONNEL 


TR> ! Ready the database: 
TR> READY PERSONNEL USING RESUMES 
TR> ! Check that RESUMES is ready: 
TR> SHOW READY 
eady sources: 
RESUMES: Relation, Rdb, snapshot read 
<_CDD$TOP . DTR$LIB. DEMO. RDB. PERSONNEL> 
o loaded tables. 


TR> ! Show the fields for RESUMES: 
TR> SHOW FIELDS FOR RESUMES 
ESUMES 
RESUMES 
EMPLOYEE_ID <Character string> 
RESUME <Segmented string> 


TR> PRINT RESUMES WITH EMPLOYEE_ID = 99800 


MPLOYEE 
ID 
RESUME 
39800 
Frank B. Harold 
1492 County Road 
Hicktown, US 54321 
3JECTIVE Junior Lab Technician 
JUCATION B.S. Chemical Engineering, Quinnipiac College, 1983. 


Hicktown Senior High School, 1979 


(continued on next page) 
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DTR> LIST RESUMES WITH EMPLOYEE_ID = 99800 
EMPLOYEE_ID : 99800 


RESUME 
Frank B. Harold 
1492 County Road 
Hicktown, US 54321 
OBJECTIVE — Junior Lab Technician 
EDUCATION B.S. Chemical Engineering, Quinnipiac College, 1983. 
Hicktown Senior High School, 1979 
DTR> 


Note 


You cannot use relational operators or the SORTED BY clause in 
RSEs that refer to segmented string fields. See the section on restric- 
tions and usage notes for more information. 


15.9.3 Storing and Modifying Segmented String Fields in DATATRIEVE 


The unstructured nature of segmented strings requires different conventions in 
STORE or MODIFY statements than are used in updating other fields in 
DATATRIEVE. 


In STORE or MODIFY statements that prompt for input, DATATRIEVE 
repeats the prompt for a segmented string field until you press the TAB key fol- 
lowed by the RETURN key in response to the prompt. Pressing only the 
RETURN key causes DATATRIEVE to redisplay the prompt for another seg- 
ment of the field. (Pressing the TAB and RETURN keys after entering text also 
redisplays the prompt for another segment.) 


DTR> STORE RESUMES 

Enter EMPLOYEE_ID: 23456 

Enter RESUME: This is the first line of the RESUME field.<RETURN> 
Enter RESUME: This is the second line.<RETURN> 

Enter RESUME: To end a segmented string, press the TAB key<RETURN> 
Enter RESUME: then the RETURN key at the "Enter" prompt .<RETURN> 
Enter RESUME: <TAB><RETURN> 
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TR> ! Now print the RESUMES record just stored: 
TR> PRINT RESUMES WITH EMPLOYEE_ID = 23456 


MPLOYEE 
ID 
RESUME 


23456 

his is the first line of the RESUME field. 
his is the second line. 

o end a segmented string, press the TAB key 
hen the RETURN key at the "Enter" prompt. 


TR> 


a STORE or MODIFY statements with a USING clause, repeat assignment 
tatements within a BEGIN-END block for each line of the segmented string 
eld: 


[R> MODIFY RESUMES WITH EMPLOYEE_ID = 23456 USING 


JN> BEGIN 
JN> RESUME = "This example modifies the RESUME field" 
JN> RESUME = "of the same record we stored in the " 
JN> RESUME = "previous example. You use as many assignment" 
JN> RESUME = "statements as you need. End the modify or" 
JN> RESUME = "store operation with an END statement." 
IN> END 
[R> PRINT RESUMES WITH EMPLOYEE_ID = 23456 
{PLOYEE 

ID 

RESUME 

13456 


1is example modifies the RESUME field 

’ the same record we stored in the 

‘evious example. You use as many assignment 
‘atements as you need. End the. modify or 
ore operation with an END statement. 


'R> 


ote that you cannot store or modify only part of a segmented string. Although 
ml create separate “segments” of the field with STORE or MODIFY state- 

ents, you cannot store or modify an individual segment. You must group assign- 
ent statements for each line of the segmented string field in the same BEGIN- 
ND block. 


1e previous examples showed that you can store or modify segmented string 


Ids interactively with DATATRIEVE. You can also create a domain. record. 
d procedure to simplify storing entire files in a segmented string field. 
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You can use the following domain and record definitions to store files in the seg- 
mented string field RESUMES: 


DTR> SHOW. TEMP_RESUME 

DOMAIN TEMP_RESUME ! TEMP_RESUME is a temporary domain used to 
! associate the file you want to 

store in the RESUME segmented 

string field with a general 

record definition that divides 

the file into records that 

DATATRIEVE can store. 


om com tae cm com 


USING TEMP_RESUME_REC ON 

TEMP_RESUME. DAT 
! TEMP_RESUME.DAT is the file you want to 
! store in the segmented string field. 


DTR> SHOW TEMP_RESUME_REC 

RECORD TEMP_RESUME_REC USING . 

01 TOP PIC X(255). ! TEMP_RESUME_REC only has one 
field of 255 

characters (the maximum size 
DATATRIEVE allows for a segment). 
Its only purpose is to separate 
the file you wish to store in a 
segmented string field into 
records. You can then use 
DATATRIEVE to store the records 
‘as individual segments in the 
segmented string. 


ee ee a ee ee er er ey 


DTR> 


For example, suppose you want to add to the resume stored in the RESUMES 
record for employee number 99800. The following example displays the resume, 
then writes it to TEMP RESUME.DAT: 


DTR> PRINT RESUMES WITH EMPLOYEE_ID = 99800 


EMPLOYEE 
ID 
RESUME 

99800 
Frank B. Harold 
1492 County Road 
Hicktown, US 54321 

OBJECTIVE Junior Lab Technician 

EDUCATION B.S. Chemical Engineering, Quinnipiac College, 1983. 


Hicktown Senior High School, 1979 
DTR> PRINT RESUME (-) OF RESUMES WITH 


DTR> EMPLOYEE_ID = 99800 ON TEMP_RESUME.DAT 
DTR> 
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ixit DATATRIEVE and make any changes you want to TEMP RESUME.DAT: 


! You have edited TEMP_RESUME.DAT and this is how it looks: 
TYPE TEMP_RESUME. DAT 

Frank B. Harold 

1492 County Road 

Hicktown, US 54321 


BJECTIVE Junior Lab Technician 


DUCATION B.S. Chemical Engineering, Quinnipiac College, 1983. 
Hicktown Senior High School, 1979 


MPLOYMENT Chemistry Tutor, Quinnipiac College (9/82 - 5/83) 
Helped freshman chemistry students learn the 
concepts of atomic weights, valence and 
covalence bonding, and empirical formulas 


EFERENCES Available upon request 
! To store the file TEMP_RESUME.DAT into a segmented string, 
! you need to know the length of the longest record in the 


! file. Use the command ANALYZE/RMS: 
ANALYZE/RMS TEMP_RESUME .DAT 


aeck RMS File Integrity 24-JUN-1985 06:28:28.09 Page i 
see DIRE (SERLE. RDEDEMO] TEMP _ RESUME . DAT; 2 


4S FILE ATTRIBUTES 
File Organization: sequential 
Record Format: variable 
Record Attributes: carriage-return 


Maximum Record Size: 255 
Longest Record: 62 


inally, you can use a procedure. MODIFY ANY RESUME. to update the 
ESUME field for employee number 99800. The procedure: 


Readies the RESUMES relation of the PERSONNEL database for MODIFY 
access. 
Readies TEMP RESUME. 


Creates a DATATRIEVE command file called SEGMENT.COM. 
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e Prints statements in SEGMENT.COM to store the file 
TEMP _RESUME.DAT in the RESUME segmented string field: 


A MODIFY USING statement that prompts the user for the employee 
number of the employee whose resume is to be updated. _ 


An assignment statement (RESUME = ) for each line of the file’ 
TEMP RESUME.DAT. The clause FORMAT (TOP) USING X(62) in 
the assignment statement uses the length of the longest record. deter- 
mined from the ANALYZE/RMS command, for the length of the seg- 
ments in the segmented string. 


° Executes the DATATRIEVE command file SEGMENT.COM. 


This example displays the procedure MODIFY ANY RESUME and executes it 
to store TEMP RESUME.DAT in the RESUME field of employee number 
99800: 


DTR> SHOW MODIFY_ANY_RESUME 
PROCEDURE MODIFY_ANY_RESUME 
1 


! Take the file named in the domain TEMP_RESUME 

! and store it in the RESUME field of the record 

! specified by the employee number entered by the user. 
' 


SET COLUMNS_PAGE = 132; 

READY PERSONNEL SHARED MODIFY USING RESUMES; 

READY TEMP_RESUME; 

ON SEGMENT.CON 

BEGIN 
PRINT "MODIFY RESUMES WITH EMPLOYEE_ID = *.’employee_id’ USING BEGIN"; 
FOR TEMP_RESUME 

PRINT "RESUME ="||"’"||FORMAT (TOP) USING X(62)||"’"; 

PRINT "END"; 

END; 

@SEGMENT 

COMMIT 

FINISH TEMP_RESUME 

END_PROCEDURE 


DTR> :MODIFY_ANY_RESUME 


Enter employee_id: 99800 
DTR> PRINT RESUMES WITH EMPLOYEE_ID = 99800 
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PLOYEE 
ID 


RESUME 
9800 
Frank B. Harold 
1492 County Road 
Hicktown, US 54321 
JECTIVE Junior Lab Technician 
UCATION B.S. Chemical Engineering, Quinnipiac College, 1983. 
Hicktown Senior High School, 1979 
PLOYMENT Chemistry Tutor, Quinnipiac College (9/82 - 5/83) 
Helped freshman chemistry students learn the 
concepts of atomic weights, valence and 
covalence bonding, and empirical formulas 
*ERENCES Available upon request 
%> COMMIT 
%> FINISH 


e DATATRIEVE command file SEGMENT.COM created by the procedure 
ks like this: 


)IFY RESUMES WITH EMPLOYEE_ID = *.’employee_id’ USING BEGIN 
3UME =" Frank B. Harold" 


3UME =" 1492 County Road" 

3UME =" Hicktown, US 54321" 

SUME = 

};UME =" " 

UME ="OBJECTIVE Junior Lab Technician" 

jUME =" " 

jUME =" " ; 

‘UME ="EDUCATION B.S. Chemical Engineering, Quinnipiac College, 1983." 
UME =" Hicktown Senior High School, 1979" 

jUME =H 

JjUME =the 

‘UME ="EMPLOYMENT Chemistry Tutor, Quinnipiac College (9/82 - 5/83)" 
UME =" Helped freshman chemistry students learn the" 

UME =" concepts of atomic weights, valence and" 

UME =" covalence bonding, and empirical formulas" 

‘UME amfet : 

UME ="REFERENCES Available upon request" 


Using DATATRIEVE with Rdb 15-27 


Note 


Source files for TEMP RESUME that contain single quotation marks 
require special treatment. This is because the procedure 
MODIFY ANY RESUME uses single quotation marks as delimiters 
for the character string literals stored by the MODIFY USING state- 
ment. For the orocedure to work, you must make sure the file contains 
two consecutive single quotation marks for every one you want stored. 


15.9.4 Restrictions and Usage Notes for Segmented String Fields 


The folowing restrictions and usage notes concern defining segmented string 
fields within RDO: 


e When you define a segmented string field in RDO with the DATATYPE IS 
SEGMENTED STRING clause. the SUB TYPE designation, if any, is 
ignored by DATATRIEVE. 


e¢ You cannot specify a MISSING VALUE IS clause when you define’a seg- 
mented string field in RDO. This is an Rab restriction. 


e You cannot specify a DEFAULT VALUE FOR DTR clause when you defin 
a segmented string field in RDO. DATATRIEVE gives a warning message 
when you ready the relation and any such default value is ignored. 


e DATATRIEVE does allow the QUERY HEADER FOR DATATRIEVE anc 
the QUERY NAME FOR DATATRIEVE clauses when you define a seg- 
mented string field in RDO. 


e Ifyou use an EDIT STRING FOR DTR clause when you define a segmente 
string field in RDO, you can only specify a T edit string. If you use any oth 
type of edit string. DATATRIEVE issues a warning message when you rea 
the relation containing the field. The length of the T edit string defaults to 
the current setting of COLUMNS PAGE. (The default for DATATRIEVE | 
80.) 


For example, if COLUMNS PAGE is set to 80, the default edit string 
for DATATRIEVE is T(80). The T(80) edit string is also used if no 
EDIT STRING has been defined in the RDO field definition. 
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Therefore, the SET COLUMNS PAGE command in DATATRIEVE can be 
used to change where a segment line breaks when printed, if no edit string 
was defined for the field in RDO. (The change takes effect on READY, 
COMMIT, or ROLLBACK). Changing the EDIT STRING clause in the Rdb 
field definition also changes the position where a segment line breaks when 
printed in DATATRIEVE. 


he following restrictions and usage notes concern the use of segmented string 
elds within DATATRIEVE: 


When you ready a domain or relation containing segmented string fields, 
DATATRIEVE places the segmented string fields last in the relation, 
regardless of the position of the segmented string when the relation was 
defined in RDO. If more than one segmented string field is defined in a rela- 
tion. the segmented string fields are placed last, in the order in which they 
were defined in the relation. 


The SHOW FIELDS command displays the order of the fields within 
DATATRIEVE and denotes which fields are segmented string fields. 


A segmented string field has no data type. DATATRIEVE cannot convert or 
validate the contents of a segmented string field. 


If a segmented string segment is longer than 255 bytes, it is output in 
subsegments of 255 bytes that break at the COLUMNS PAGE setting (or at 
the position in the T edit string, if one is specified in the field definition in 
RDO). If a segment is shorter than the current COLUMNS PAGE SetOns 
the segment is left-justified and blank-filled. 


When you use a PRINT statement to display a segmented string field. the 
header for the segmented string field begins on a separate line. following the 
header lines of fields of other data types. If more than one segmented string 
field is in the domain, each field has its own header. DATATRIEVE centers 
the header based on the current COLUMNS PAGE setting. 


Each segment of a segmented string starts in the first column. The T edit 
string defined for each segmented string field (or the COLUMNS PAGE set- 
ting. if none is defined) controls where a segmented string line breaks. 
DATATRIEVE displays a blank line for a missing segmented string. 
Individual segments cannot be displayed separately. 


When you use a LIST statement to display a segmented string field, 
DATATRIEVE prints the segments of the field below the field header, 
instead of beside it. DATATRIEVE displays a blank line for a missing ae 
mented string. 


You cannot use the DISPLAY statement with a segmented string field. 
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e You cannot store segments larger than 255 bytes in a segmented string field 
through DATATRIEVE. This is due to a general DATATRIEVE limit on the 
number of characters that can be input on a line. If this segment exceeds 
255, the segment will be truncated. 


¢ You must enter all segments of a segmented string in a single STORE or 
MODIFY statement. Individual segments cannot be entered or retrieved 
separately. 


In STORE or MODIFY statements that prompt for input, DATATRIEVE 
repeats the prompt for each segment to be entered in the segmented string. 


Pressing the TAB key followed by the RETURN key in response to a promp 
for a segmented string field terminates the segmented string if data has 
already been entered in response to previous segment prompts. Pressing the 
TAB key followed by the RETURN key in response to the initial prompt for 
a segmented string field results in nothing being stored in the field. 


¢ You cannot modify portions of a segmented string field. The MODIFY state 
ment creates an entirely new segmented string for a record. It does not 
update an existing segmented string. 


e Data can be stored in segmented strings only in response to segment 
prompts or as character string literals assigned to a segmented string field i 
a STORE or MODIFY USING statement. You cannot assign values of field: 
or declared variables to a segmented string field. 


If data is input as a character string literal ina STORE or MODIFY USINC 
statement, each character string represents one segment. The field name 
must be repeated for each character string literal being assigned to a seg- 
ment of the segmented string field. As soon as a new field name is encoun- 
tered, the string is terminated. 


e You cannot retrieve or store segmented string fields from remote domains. 
When you ready a remote domain, DATATRIEVE ignores the segmented 
string fields and gives a warning message naming the fields. DATATRIEVE 
does ready the remote domain. however, and you can retrieve or store fields 
of other data types. 


e Segmented string fields cannot be used with forms or plots. 


¢ You cannot refer to segmented strings with the following elements of a 
record selection expression: 


- Relational operators 


- Boolean operators (AND, OR, NOT, BUT) 
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- SORTED BY clause 
- REDUCED TO clause 
- CROSS clause 


5.10 Modifying the Structure of an Rdb Domain or Relation 


yu cannot modify the structure of an Rdb relation or view relation using 
ATATRIEVE. If you want to add, change, or delete fields or indexes, you 
ust restructure your Rdb database using techniques described in your Rdb 
cumentation. 


5.11 Ensuring Data Security 


ke any other domain, each Rdb domain has an associated DATATRIEVE ACL 
at specifies access privileges. There is also an ACL associated with the database 
th name. In addition, Rdb provides an access control list for each relation in 

e database. When a user readies a domain, DATATRIEVE first checks the 
main’s ACL, then checks the database path ACL, and finally checks Rdb access 
ivileges for the associated relation. Users are denied the requested access if any 
these access control lists denies them the required privilege. 


you want the Rdb access control list to be the main means of access control for 
lb domains, you might consider opening up the DATATRIEVE ACLs to allow. 
users READ, WRITE, MODIFY. and EXTEND privileges. This allows users 
ass through” to the Rdb access control list. 


you are not using domains to access the database, the ACL associated with the 
tabase path name and the Rdb access control list are the only means of access © 
ntrol. In this case, you have to maintain only two access control lists. 


}.12 Validating Data for Rdb Relations and Domains 


ep in mind that when you are storing into or modifying fields whose definitions 
2 common to more than one Rdb relation, you affect values only in the relations 
at you specify. You do not automatically change data values in the same fields 
any other relations. 


ie EMPLOYEE ID field definition, for example. is common to several Rdb rela- 
ms in the PERSONNEL database. A user could assign an EMPLOYEE ID 

lue for Jack Jones in the EMPLOYEES relations and give him a different 
APLOYEE ID value in the JOB HISTORY relation. You should design valida- 
n procedures to protect against such an occurrence. Design your database so 
at the minimum number of identical fields exist from one relation to another. 
nit common fields to the keys you need in order to match records. 
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One way to check data for validity is through Rdb’s VALID IF clause of the Rdb 
DEFINE FIELD statement. In addition, with Rdb/VMS, you can use the 
DEFINE CONSTRAINT statement, which is more flexible for checking validity. 
(Note that one option of the DEFINE CONSTRAINT statement specifies that 
the validation criteria are not evaluated until a COMMIT statement is issued. If < 
database is set up to check constraints at the time a COMMIT statement 
executes, validation errors can occur later than interactive DATATRIEVE users 
expect to receive them.) 


15.13 Optimizing Performance 


To optimize DATATRIEVE performance, keep these points in mind when using 
DATATRIEVE with Rdb: 


e Avoid using the FIND statement unless the resulting collection contains a 
small number of records. After you form a collection, DATATRIEVE cannot 
use the Rdb index structure to search the data contained in the collection. 
Data retrieval using keyed fields to search relations is faster than an exhaus 
tive search of large collections. For the same reason, forming a new collec- 
tion from another collection is likely to be time-consuming. If a collection 
contains a small number of records, however, you may find that 
DATATRIEVE responds more quickly when you specify that collection as a 
record source. 


e Using the READY DATABASE command to access your Rdb database 
works more quickly than using domains defined for relations. Therefore, 
define domains for relations only when you cannot do what you want by 
readying the entire database directly. 


¢ DATATRIEVE and Rab use different default settings for waiting on locked 
records. Using the DATATRIEVE default may cause Rdb to generate error 
messages you do not expect. In DATATRIEVE, when your Rdb transaction 
encounters a locked record, the default setting (SET NO LOCK WAIT) 
causes Rdb to generate an error message and returns to the DATATRIEVE 
prompt. In Rdb, the default setting (START TRANSACTION WAIT) is for 
transaction to wait until a locked record is released and then continue the 
operation. 


The following example shows the error message generated when a user trie: 
to update a locked record of the sample EMPLOYEES Rdb domain with thi 
default DATATRIEVE setting in effect: 


DTR> MODIFY FIRST_NAME 

Enter FIRST_NAME: Norman 

*+RDB-E-LOCK_CONFLICT, NO WAIT request failed because resource was 1 
~RDMS-F-LCKCNFLCT, lock conflict on area 25 

DTR> 
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To change the setting in DATATRIEVE, issue the SET LOCK WAIT com- 
mand. Instead of generating the error messages and returning to the 
DATATRIEVE prompt, your Rdb transaction will wait until the other user 
begins another transaction and the record is released. (DATATRIEVE com- 
mands and statements that begin Rdb transactions are READY, COMMIT, 
and ROLLBACK.) 


Changing the default setting to LOCK WAIT will affect performance in the 
sense that your transaction must wait for a locked record to be released. 


Using DATATRIEVE with Rdb 15-33 


Accessing Remote Data 16 


“his chapter explains how to define network domains and access distributed 
lomains.. 


I6.1 Defining Network Domains and Accessing Remote 
Domains | 


Vith VAX DATATRIEVE, you can access domains defined on other systems 
nked to yours by the DECnet network. Each system must have DATATRIEVE 
astalled. In the following discussion, the term “local” refers to your system and 
he term “remote” refers to a system connected to yours by the DECnet network. 


‘he term “network domain” refers to the domain you define at your local node 
ontaining a network address. The term “remote domain” or “distributed . 
omain” refers to the domain located at the remote node. 


‘o access a remote domain, you must tell DATATRIEVE the network address of 
he remote domain. You can do that in one of two ways: 


You can include the network address of the remote domain in the READY 
command: 


DTR> READY CDD$TOP.DEPT32.SMITH.PERSONNEL AT BIGVAX 
DTR> 


At your local node, you can define a domain (called a network domain) that 
contains the address of the remote domain. Then you ready the network 
domain at your local node just as you would any domain definition: 


DTR> DEFINE DOMAIN REM_PERSONNEL 

DFN> USING CDD$TOP .DEPT32.SMITH.PERSONNEL 
DFN> AT BIGVAX"SMITH PASSMETHROUGH" ; 

DTR> READY REM_PERSONNEL 
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When you ready a remote domain, either directly using the network address 
in the READY command or by readying a local domain that contains a network 
address, DATATRIEVE: 


e Recognizes that the desired domain resides at another node in your network 
e Starts a process on that remote node 


e Invokes the DATATRIEVE Distributed Data Manipulation Facility (DDMF) 
at the remote node to process the DATATRIEVE statements that refer to 
the domain at that node 


¢ Terminates the remote process when you finish the domain 


The DDMF keeps a trace file of your requests and its responses. It writes this file 
to the login directory of the remote process. If the remote node is a VAX/VMS 
system. the trace file is NETSERVER.LOG. If the remote node is a PDP-11 sys- 
tem, the trace file is DDMF.LOG. 


If the DDMF is handling more than one domain, the remote process ends when 
you finish the last domain. 


The following sections explain the process of defining network domains and how 
to access remote domains. 


16.1.1 Defining Network Domains 


To define a network domain, you define a DATATRIEVE domain at the local 
node that specifies the link with the domain definition at the remote node. 


The following example defines a network domain for a domain on a remote 
VAX/VMS system: 


DIR> DEFINE DOMAIN PERSONNEL 

DFN> =; USING CDD$TOP .DTR$USERS . CUVERDALE . PERSONNEL 
DFN> AT BIGVAX"CUVERDALE SESAME" ; 

DTR> 


The following example defines a network domain for a domain on a remote 
PDP-11 system: 


DTR> DEFINE DOMAIN CDD$TOP.DEPT39.PERSONNEL USING PERSONNEL 
aN AT ELEVEN" .USERNAME *.PASSWORD" ; 
R> 
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7ou use the following format: 
)EFINE DOMAIN path-name USING <------- (1) 
remote-domain-name <----------- (2) 
AT node-spec <----------- (3) 
iee the VAX DATATRIEVE Reference Manual for the full syntax. 


‘he format: 


1. Specifies a name for the network domain 


The path name you give the network domain can be a given name, a relative 
path name, or a full path name. . 


The results of specifying each type of name and the consequences for 
extracting and moving the definition are the same for network domains as 
for any other domain. 


iN 


Specifies the name of the domain at the remote node 


If the remote domain is on a VAX/VMS system, you can specify the remote 
domain name using either the given name or the full path name of that 
domain. 


If you use the full path name, your access to the remote domain is indepen- 
dent of the default dictionary directory used by the remote process running 
DATATRIEVE. If you use the given name, you access either the CDD 
default dictionary for that process, or a CDD dictionary identified in the 
login command file of the remote process that rans DATATRIEVE. 


If the remote domain is on a PDP-11 system, you specify only the domain’s 
given name. Otherwise, the format for referring to remote domains is the 
same for both the VAX and the PDP-11 systems. 


Note that the remote domain you refer to in a network domain definition 

is no different from any other DATATRIEVE domain. It specifies the 
relationship of a particular record definition and a data file. (At remote 
VAX/VMS systems, a DBMS or Rdb domain can also be the access path to 
a DBMS or Rdb database.) The remote domain must be defined at the 
remote node during a DATATRIEVE session running on that remote node. 
A person or program local to that system can invoke DATATRIEVE to 
enter the domain definition, or a person or program running on that system 
as a remote terminal can enter the definition. 
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3. Specifies the network address 
The network address corresponds to node-spec in the preceding format. 


If the login procedure used by the remote process does not supply the nec- 
essary login information (user name, password, and, optionally, account 
name), either the person readying the network domain or the network 
domain definition must supply this information. 


You can use any of the following formats to specify the network address 
and to provide the best level of access security for your installation: 
e node-name” username password [account-name]” 

Examples of this format are: 

BIGVAX"WARTON KNOCKKNOCK DEPT32" 


ELEVEN"LINTE LETMEIN" 


When you specify the network address using this format, users do not 
have to supply login information when readying the network domain. 


e  node-name”*.username-prompt *.password-prompt [* account- promp 
Examples of this format are: | 
WINKEN"*+.USERNAME *.PASSWORD *.ACCOUNT" 
VAXTWO"*.’user name’ *.’password’" 


PDPTWO"*.’user name’ *.’password’" 


When you specify the network address using this format, users are 
prompted for login information when they ready the network domain. 
This method provides the best security. 


e node-name 
Two examples of this format are: 
BIGVAX 
ELEVEN 


When you specify the network address with this format, the 
account used by the remote process must provide login information 
automatically. 
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If you prefer, you can combine elements from the first two formats. For 
example, you can explicitly specify the user name and specify a prompting 
value expression for the password: 


SNOOPY"CLARK *.PASSWORD" 


6.1.2 Accessing Remote Domains 


s you have seen, you can access a remote domain by either: 


Readying a network domain (the domains you learned to define in the pre- 
vious section) 


Including the network address in a READY command 


he next two sections show how to access a remote domain both ways. 


3.1.2.1 Readying a Network Domain -- Readying a network domain makes 
stributed processing transparent to the DATATRIEVE user. Depending upon 
yw you specify login requirements in the network address of the domain defini- 
on, the user may have to enter a user name or password. The user need not be 
mcerned with the actual location of the domain, however, as that is already 
fined in the network domain definition. 


1e following example readies the network domain REM PERSONNEL, whose 
finition explicitly specifies user name and password in the network address: 


R> READY REM_PERSONNEL 


R> 
R> SHOW REM_PERSONNEL 


MAIN REM_PERSONNEL USING CDD$TOP .DEPT32.SMITH.PERSONNEL 
BIGVAX"SMITH PASSMETHROUGH" ; 


1e following example readies the network domain REM SALES whose defini- 


m specifies prompting value expressions for user name and password in the net- 
wrk address: 


R> READY REM_SALES 

ter USERNAME: GREEB 

ter PASSWORD: 

R> 

R> SHOW REM_SALES 

MAIN REM_SALES USING SALES AT ANODE"*«.USERNAME. «.PASSWORD"; 
R> 
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16.1.2.2 Readying a Remote Domain Directly -- When you ready a remote 
domain directly, you specify the name of the remote domain and its network 
address in the READY command. The formats and results for specifying a net- 
work address in the READY command are the same as those for including the 
network address in a network domain definition. See the third step, specifying a 
network address, in the section on defining network domains. 


The following example readies a remote domain on a VAX/VMS system. The 
command specifies a full dictionary path name and assumes a default DECnet 
account in the network address: 


DTR> READY CDD$TOP.DEPT32.PERSONNEL AT BIGVAX 
DTR> 


The next example readies a remote domain on a PDP-11 system. The network 
address specifies the login account assigned to the user VOJTEK. The prompting 
value expression for the password ensures that the password is not displayed on 
the terminal as it is entered: 


DTR> READY PERSONNEL AT ELEVEN"VOJTEK *.PASSWORD" 
DTR> Enter PASSWORD: 
DTR> 


16.1.3 Results of Accessing Remote Domains 


There are some facts common to both ways of accessing remote domains. 


Whichever method you choose, the remote process running DATATRIEVE 
executes a login command file, just as you do when you log in to your local sys- 
tem. Depending in how you specify a network address, the remote process can los 
in to a specific account or it can log in to a default DECnet account. 


For example. the command READY PERSONNEL AT BIGVAX does not specif 
a user name. Therefore, it starts a remote process using a default DECnet 
account. (The guide for installing DATATRIEVE explains how to set up a default 
DECnet account for DATATRIEVE on a VAX/VMS system.) In this case, the 
login procedure executes the login command file for the default DECnet account. 


On the other hand, the command READY PERSONNEL AT BIGVAX”SWAZY 
ITSME” starts a remote process using the login account assigned to user Swazy 
The login procedure executes the login command file for Swazy’s account. 


In addition to providing security information such as user name and password, 


you must make sure the remote process uses the correct dictionary and system 
directories when it invokes DATATRIEVE and readies the domain for you. 
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Jn a VAX/VMS system, the login command file for the account used by the 
emote process can include commands that set any defaults not included in the 
tetwork address and needed by the remote process running DATATRIEVE. 
Jowever, the login file should not execute commands that are appropriate for 
nteractive mode and that might cause a network process to fail. (Assignments to 
“T: can fall into this category.) 


‘he following example illustrates some helpful commands that you might want to 
aclude in a login file for an account on a remote VAX/VMS system. The example 
ssumes that there are no commands preceding the first line that might cause a 
etwork process to fail. 


IF F$MODE() .EQS. "NETWORK" THEN GOTO NETWORK_PROCESS 


NETWORK _PROCESS: 

SET DEFAULT [HAMOND.PERSONNEL. DATA] 

ASSIGN "CDD$TOP.HAMOND.PERSONNEL" CDD$DEFAULT 
EXIT © 


he SET DEFAULT command moves the network process to the VAX/VMS 
irectory that contains the data file. This is necessary if the login directory does 
ot contain the data file and if the definition of the domain being readied does not 
yntain a full file specification for the data file. The ASSIGN command sets the 
gical name CDD$DEFAULT to the dictionary containing the definition of the 
omain being readied. This is necessary if this information is not included in the 
etwork address. The EXIT command exits the login command file so that subse- 
1ent commands inappropriate for a network process are not executed. 


or a PDP-11 system, you can use a SET DICTIONARY command in a 
ATATRIEVE-11 QUERY .INI file to access the dictionary directory you 

ant to use when the remote process invokes DATATRIEVE. This is unneces- 
iry. of course, if the dictionary file containing the domain definition is in the 
gin directory. 


}.1.4 Restrictions on Using Remote Domains 


‘hen you access data located on remote systems, note the following restrictions: 


Using a simple DATATRIEVE domain that includes a remote node name in 
the specification for the data file can slow DATATRIEVE response time. 
Avoid using this method to access data on other systems. Instead. use the 
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methods explained in this chapter to ensure optimum DATATRIEVE 
performance. 


e The CONTAINING operator does not work with a prompt for remote 
domains. For example, the following PRINT statement does not work: 


PRINT REMOTE_YACHTS WITH BUILDER CONTAINING *.BUILDER 


DATATRIEVE uses a fixed-length field to transmit the prompt value to the 
remote server. Trailing spaces are appended to any value shorter than the 
length of this field. 


¢ You cannot use a Boolean expression containing the relational operators IN 
or ANY in a record selection expression with a remote domain or collection 
as its source. 


e You can use remote domains or collections in a CROSS clause only if both of 
the following conditions are met: 
- The remote domains or collections reside on the same remote node. 
- You access the remote domains or collections with the same account, 


user name, and password. 


e When validation checks are made for data entered in response to a prompt, 
distributed DATATRIEVE does not reprompt when validation errors occur. 
A validation error causes the statement being processed to abort. 


¢  Inarecord selection expression with a remote domain as its source, you can- 
not use value expressions that require computations involving remote data. 


e If aremote domain contains an elementary field that is also a list field. 
explicitly attempting to access it generates the error message: 


[DDMF] field is not a list. 


This occurs if the field is defined using the following format: 


O06 ABSTRACT PIC X(80) OCCURS O TO 10 TIMES. 
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In this case, you need to change the format of the field definition. If the field 
is defined in the following way, you can explicitly access the field TEXT: 


O06 ABSTRACT OCCURS O TO 10 TIMES. 
O08 TEXT PIC X(80). 


You cannot ready a remote Rdb database by specifying a database path name 
in a READY command that uses the AT syntax. You must first create 
domain definitions on the remote node for each relation you want to access. 
You can then ready the database using these domains. 


The following example does not work: 


DTR> READY CDD$TOP.DTR$LIB.DEMO.RDB.PERSONNEL AT 
(Looking for Node Specification] 

CON> DEPT42"SMITH PASSWORD" 

[DDMF] You can not READY a database with an alias. 
{[DDMF] Statement abandoned due to error. 


If you define a DATATRIEVE domain on the remote node for each relation 
in PERSONNEL, you can ready and access each relation in the remote Rdb 
database PERSONNEL. In this example, the user defines a DATATRIEVE 
domain on the remote node DEPT42 for the Rab relation 

SALARY HISTORY in the database PERSONNEL. 


DTR> DEFINE DOMAIN SALARY_HISTORY USING SALARY_HISTORY OF 
wae DATABASE CDD$TOP .DTR$LIB.DEMO.RDB.PERSONNEL ; 
> 


Then the user can ready the remote domain from the local node: 


DTR> READY SALARY_HISTORY AT DEPT42"SMITH PASSWORD" 
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Name Recognition and Single Record Context A 


‘hen you use a field name as a value expression and you display, modify, or erase 
1e or more records, DATATRIEVE determines exaetly which record or records 
e the targets of the action you propose. 


yr each of these actions, DATATRIEVE must first determine the context within 
rich the action occurs. The context is the set of conditions that govern the way 
ATATRIEVE recognizes field names and determines which records are the tar- 
‘ts of DATATRIEVE statements. Understanding the way DATATRIEVE man- 


‘es context is especially important when you pee nesting DATATRIEVE 
atements. 


.1. Establishing the Context for Name Recognition 


ATATRIEVE does not require that every field name be unique. You can use the 
me name in several record definitions. You can even use the same name several 
nes in the same record definition, as long as the fields with identical names do 
t have the same level number in one group field. 


r example, both the YACHTS and OWNERS domains have group fields named 
(PE, and both group fields contain elementary fields you can refer to with the 
mes BUILDER and MODEL. (In YACHTS, DATATRIEVE recognizes the 

ery name BUILDER as equivalent to MANUFACTURER. Other query names 
‘YACHTS are SPECS, LOA, and DISP.) Figure A-1 shows the fields in both 
mains and points out the duplicate names. 


hen you work with several record streams from the same domain, the field 
mes in all record streams are identical. Whether you form collections or record 
‘eams of records from the YACHTS domain, DATATRIEVE has a mechanism 
‘identifying which record to act on when you want to retrieve or change data 
im only one field of one record. 


OWNER 

NAME 

BOAT _NAME BOAT 

TYPE —_—S- “TYPE 
BUILDER ——» MANUFACTURER (BUILDER) 
MODEL _—_— SS MODEL 

SPECIFICATIONS (SPECS) 
RIG 


LENGTHOVERALL (LOA) 
DISPLACEMENT (DISP) 
BEAM 

PRICE 


MK-01592-00 


Figure A-1: Duplicate Field Names in YACHTS and OWNERS 


When you understand the way DATATRIEVE establishes the context for recog- 
nizing names, you can use the names of domains, fields, collections, and variable: 
to form the simple and the complex relationships DATATRIEVE provides. One ¢ 
the keys to mastering the use of context is understanding the two DATATRIEV. 
context stacks. 


A.1.1. The Right Context Stack 


When you issue a statement. DATATRIEVE builds a context stack, a linked list 
that controls DATATRIEVE’s search for names to match the ones you use in 
statements. The context stack consists of context blocks. or lists of names. Thes 
context blocks are linked together by pointers that control the sequence of 
DATATRIEVE’s search for values to associate with the names you use in 
statements. 


DATATRIEVE searches the right context stack for values to associate with 
names you use in print lists, Boolean expressions, and the right side of assign- 
ment statements such as x = y. See Section A.1.3 for a discussion of the left co: 
text stack. 


A.1.1.1. The Content of a Context Block -- When you use a record selection 
expression. DATATRIEVE creates a context block to establish a context for 
name recognition. That context block contains, among other things. a list of 
names. 


At the top of the list is a slot for the name of a context variable (see Section 
A.1.2.1). Next is the name of the domain referred to in the record selection 
expression. The rest of the list contains the names of fields in the record associ- 
ated with that domain. Those field names are arranged according to the field tre 
associated with that record. 
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‘he field tree contains the names of all the group fields, elementary fields, 
‘(OMPUTED BY fields, REDEFINES fields, and lists in the record and pre- 
erves the hierarchical relationships among them. 


Vhen DATATRIEVE searches for a name in the context stack, it looks for a 
alue to associate with that name. The search ends, and DATATRIEVE takes 
1e associated value when it finds the first name that matches the one in your 
tatement. 


. DATATRIEVE name can consist of several names joined together. (See Section 
1.2.2.) They resemble dictionary path names in form and function. To be recog- 
ized, these compound or qualified names you supply must represent a valid path 
irough the hierarchy of a context block and the field tree it contains. 


Then DATATRIEVE encounters a name, it begins its search in the context block 
a top of the stack. DATATRIEVE first looks at the slot in the context block 
sserved for a collection name or the name of a context variable. For unnamed 
URRENT collections, this slot contains the name CURRENT. For named 
URRENT collections, the name CURRENT and the collection name are equiv- 
ent. Named collections that are not the CURRENT reer have the collec- 
on name in this slot. 


the top block on the context stack refers to a record stream, this slot is empty 
iless you use a context variable in the RSE that forms the record stream. The 
mtext variable gives a record stream a temporary name; this name fills the first 
ot in the context block for these named record streams. 


DATATRIEVE finds that the first segment of a qualified name matches the 
ame in the collection name/context variable slot, it continues its search in that 
ock for a match for the rest of the name. If the name in your statement does not 
atch the name in the collection name/context variable slot, or if that slot is 

npty, DATATRIEVE continues to look through the first context block to find ; a 
atch. | 


ext in the context block is ne name of the source of the records referred to by 
at block. For collections and record streams, that source can be the domain 
ime or the name of a list for hierarchical records. The source can also be the 
ime of a collection if you use the collection as the basis for a record stream in a 
IR statement and use a context variable. 


the source name does not match the name in your statement. DATATRIEVE 
‘xt looks for the name in the slot reserved for names. 


2xt DATATRIEVE looks at the name of the top-level (the 01 level) field name. 
no match occurs, DATATRIEVE looks at each succeeding field name in the 

der they are displayed when you enter a SHOW FIELDS command. That order 
n take you through the entire hierarchy of the field tree, traversing first the left 
anch and then the right wherever there is a branching point in the hierarchy. 


Name Recognition and Single Record Context A-3 


If DATATRIEVE finds no match in the first block on the context stack, it goes t¢ 
the next context block on the stack and begins its search there. 


DATATRIEVE stops its search as soon as it finds an exact match for the name i 
your statement. Then it associates the value assigned to the name on the context 
stack with the name of the field in your statement. 


If DATATRIEVE finds no match for the name in any of the context blocks, it dis 
plays a message on your terminal that the field name is either undefined or used 
out of context. The only remedies are to change the context so that the name in 
your statement resolves properly or to remove any ambiguity by qualifying the 
name further with group field names or context variables. 


For the sake of clarity, the following description of the various types of context 
blocks starts with the bottom of the context stack, that is. with the context block 
that DATATRIEVE checks last. 


A.1.1.2 Global Variables -- The bottom context block contains the names of 
any global variables you have established and have not released. This block is dif- 
ferent from the others on the stack because its content is not determined by a 
record selection expression. Nevertheless, DATATRIEVE treats the name of a 
global variable as though it were the name of a field in a simple record. Just as 
DATATRIEVE associates the value of a field with the field name, DATATRIEVI 
associates the value of a global variable with its name. 


DATATRIEVE looks at the global variables last when trying to find a name to 
match one in your statement. No two global variables can have the same name. 
When you issue a DECLARE statement at command level (indicated by the 
DTR> prompt), DATATRIEVE checks the names of the global variables you 
have declared. If it finds one with the same name, it releases the old variable and 
its value and replaces it with the new one. DATATRIEVE initializes the new var: 
able with a default value, a missing value, a zero. or a space depending on the 
clauses you include in the DECLARE statement. 


A.1.1.3 Collections -- The next higher set of blocks in the context stack refer: 
to existing collections. Each collection with a block on the context stack must 
have one record singled out as a selected record. Although a collection can have ; 
number of records in it, only one of those records can be used in the search for 
the context of aname. DATATRIEVE can assign only one value to the name. 
Consequently. that one value can come from only one of the records in the 
collection. 


Remember. the reason for resolving the context of a name you use in a statemer 
is to assign to the name a value for use in the statement. 
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or an existing collection, you can designate one record at a time as the selected 
cord for that collection. The SELECT statement lets you designate the selected 
scord in a collection by relative reference (FIRST, NEXT, PRIOR, LAST, and 
‘ITH Boolean) or by absolute reference to the position number of the record in 
ie collection. A collection has a block on the context stack only if it has a 

lected record. 


you have more than one existing collection with a selected record, the block 
amediately above the one for global variables refers to a named collection with a 
lected record. That collection is the one you formed with a FIND statement 
>fore you formed any of the other collections that have selected records. 


he rest of the context blocks for the collections with selected records are ordered 
cording to the sequence in which you formed them. not the order in which you 
itered the SELECT statements to establish the selected records. 


the CURRENT collection has a selected record, the context stack contains a 
ock referring to the CURRENT collection. That block is above the blocks of all 
her collections; that is, DATATRIEVE searches for names in the context block 
‘the CURRENT collection before it searches the context block of any other 
lection. 


he key to understanding the way DATATRIEVE recognizes names is that 
‘cept for the global variables. the context stack is ordered on a “last-in, first- 
it” basis. The most recently formed context block is the one DATATRIEVE 
‘arches first. 


ou do not have to rely on your memory to recall the order in which you formed 
yur existing collections. You need only issue a SHOW COLLECTIONS com- 
and. DATATRIEVE displays the most recently formed collection (always the 
URRENT collection, whether it has a name or not) at the top of the list and the 
Idest” one at the bottom. 


ith the SHOW collection-name command, you can inspect each existing collec- 
yn to see how many records are in the collection, whether it has a selected 


cord. and, if it does, what the position number of the selected record is in the 
lection. 


DATATRIEVE searches the context stack and does not find a match for the 
ume in your statement, it displays an error message that may seem puzzling 
less you understand the way DATATRIEVE forms the context stack: 


eld "name" is undefined or used out of context 


yu may know the name has been defined and that it is the name of a field in a 
cord associated with one or more existing collections. If, however, none of the 
llections containing that field have selected records, DATATRIEVE cannot tell 
the field is defined or not. 
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If a collection containing the named field has no selected record, that collection 
has no block on the context stack. Consequently, DATATRIEVE neither finds a 
match for the field name nor has a way of discovering from the search of the con- 
text stack if the field name is defined at all. 


The order of context blocks at the higher levels of the context stack depends on 
the order in which DATATRIEVE encounters the elements containing names 
associated with values. The order of the following sections does not imply any rel- 
ative position on the stack. Only the order DATATRIEVE encounters those ele- 
ments determines their order on the stack. 


A.1.1.4 Record Streams -- Before DATATRIEVE looks at the context block o: 
the most recently formed collection with a selected record, it looks at the context 
blocks created explicitly in the statement. One type of context block created by a 
statement refers to the field names of a record stream formed by a statement. 


Context blocks of record streams act differently from those of collections. The 
context block for a collection stays on the stack as long as the collection has a 
selected record. The context block of a collection is removed from the stack only : 
you release the collection or remove its selected record with a DROP statement. 


The context block for a record stream, however, stays on the stack only as long a 
the statement containing it is being executed. When DATATRIEVE finishes pro- 
cessing the statement, the block added to the stack is removed from the context 
stack and is not available when DATATRIEVE rebuilds the stack after it encoun: 
ters the next statement. 


Only three statements make lasting changes to the context stack: 


e FIND 


The FIND statement can remove the CURRENT collection from the contex 
stack by forming a new CURRENT collection. The new CURRENT collec- 
tion releases the old collection but does not put a block on the context stack 
because a newly formed collection has no selected record. 


e¢ SELECT 


The SELECT statement puts a collection on the context stack by establish- 
ing a selected record. SELECT cannot change the relative order of collec- 
tions on the stack. That order is determined by the relative order in which 
you formed the collections with the FIND statement. 
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DROP 


The DROP statement removes collections from the context stack by drop- 
ping the selected record from the collection. The SHOW collection-name 
command still notes the position number of the previously selected record, 
but a parenthetical note points out that the record has been dropped: 


DTR> SHOW CURRENT 
Collection CURRENT 

Domain: YACHTS 

Number of Records: 113 

Selected Record: 57 (Dropped) 
DTR> 


The selected record has been removed from the collection. and cannot be 
retrieved unless you form a new collection that contains it. 


hese three statements, however. share a restriction that separates them from all 
cher statements: you cannot use FIND, SELECT, or DROP statements in com- 
yund statements. They must be entered at command level by themselves. 
urthermore, these statements do not form temporary record streams; they 

‘fect only collections. 


ou can, however, have several context blocks for record streams on the context | 
ack at one time. The block for a record stream stays on the context stack until 
ATATRIEVE finishes the statement. Because you can nest statements in FOR 
ops, BEGIN-END blocks, IF-THEN-ELSE statements, THEN, and WHILE 
atements. the inner statements can form record streams before DATATRIEVE 
1ishes the outermost statement. 


ATATRIEVE has to keep the context of outer statements separate from that of 
ner ones. It keeps them separate by putting a block on the context stack when 
encounters an element that requires one. DATATRIEVE begins processing 
mpound statements with the outermost statement and works progressively 
ward the innermost one. The context blocks it forms for elements in the inner- 
ost statement are at the top of the stack when the innermost statement is being 
‘ocessed. 


hen DATATRIEVE finishes processing the innermost statements, it removes 
e blocks created by that statement. DATATRIEVE works its way back out 
ward the outermost statement, removing blocks created by statements as soon 
it finishes processing the statement. | 


xr example. in the case of nested FOR loops, the context block for the inner- 
ost FOR loop is higher in the stack than the blocks for the outer loops. 
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When DATATRIEVE completes the execution of the innermost loop, it removes 
the context block of that FOR statement, leaving those of the outer FOR state- 
ments on the stack. As DATATRIEVE completes each loop, the context block for 
that loop is removed from the stack. This same pattern of events applies to state- 
ments in BEGIN- END blocks. 


When a statement that forms a record stream is followed by a second statement 
that is not contained in the first, DATATRIEVE removes the context block cre- 
ated for the first statement from the stack and puts a context block for the sec- 
ond statement in its place. 


For example. in a BEGIN-END block, one PRINT statement containing an OF 
rse clause follows, another. The context block of the first statement is in effect 
only during the execution of that first statement. That block is replaced by the 
one for the second PRINT statement when DATATRIEVE begins processing the 
second statement. 


DATATRIEVE handles the context block of a FOR loop the same way it handles 
statements containing an OF rse clause. 


DATATRIEVE creates four other types of context bocks that affect the order of 
the context stack: those for local variables, VERIFY clauses, VALID IF clauses, 
and context variables. 


A.1.1.5 Local Variables -- Local variables are variables defined in compound 
statements, A local variable and its effect on the context stack last only from the 
DECLARE statement that defines it until DATATRIEVE completes the execu- 
tion of the statement containing the DECLARE statement. 


A.1.1.6 VERIFY Clause in the STORE Statement -- Like the context for local 
variables, the context for resolving field names in a VERIFY clause of the 
STORE statement is short-lived. The STORE statement does not access or 
change any existing record. Consequently, for each STORE statement 
DATATRIEVE creates a context block to associate the field names with the val- 
ues in the new record. DATATRIEVE executes the VERIFY clause after you 
have assigned values to all the fields prescribed by the syntax of the statement, 
but before DATATRIEVE stores the record in the data file. 


A.1.1.7 VALID IF Clause in a Record Definition -- When you assign a value to 
a field name in either a STORE or MODIFY statement, DATATRIEVE looks in 
the appropriate record definition for a VALID IF clause. If the value is 
unacceptable according to the conditions specified in the VALID IF clause, 
DATATRIEVE displays a message on your terminal and reprompts you for an 
acceptable value. It uses the same context to associate the field name with your 
response to the reprompt. 
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‘he context for resolving field names in the VALID IF clause is established in one 
f two ways: 


By the context block set up for the STORE statement 
By the context block set up for the the MODIFY statement 


1 either case, the value associated with the field name is the one just assigned to 


by your response to a prompt or by an assignment statement in the USING 
ause of the STORE or MODIFY statement. 


'‘ATATRIEVE executes the VERIFY clause only after the values you assign 
1eet the conditions of VALID IF clauses in the record definition. As a result, 
1ere can be no conflict between the context established for these two clauses. 
he context for the VALID IF clause no longer exists when DATATRIEVE 
secutes the VERIFY clause. 


.1.2 Using Context Variables and Qualified Field Names 


he ways of establishing context discussed to this point deal with resolving the 
mnections between names and values by finding the first instance of a valid field 
ame or variable name. When several context blocks on the stack contain fields 
ith the same names, you need a way to skip over some instances of the name to 
st to the field that contains the value you want to retrieve. 


ATATRIEVE gives you two methods of forcing name recognition: context 
triables and qualified field names. Although they require different actions from 
uu, these two methods have an underlying similarity. 


1.2.1. Context Variables as Field Name Qualifiers -- A context variable is a 
ummy variable specified in a record selection expression for the purpose of name 
cognition. When DATATRIEVE encounters a context variable, it puts a new 
ock on the context stack. That new block connects the name of the context vari- 
lle with the field names and values of the records identified by the record selec- 
yn expression. 


1e context established by the context variable lasts until DATATRIEVE com- 
ates the execution of the statement containing the record selection expression 
which the context variable occurs. However, that context does not affect any 
ter loops or nesting statements that contain the statement in which you use the 
ntext variable. 


context variable, however, does affect all inner statements nested in the state- 


ent that contains the record selection expression in which the context variable 
curs. 
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You can use the context variable as a prefix for each field name of the records 
identified by the record selection expression. Citing a field name with a context 
variable prefix can make a field name unique, even when the domains and field 
trees of a record in a record stream are identical. 


Putting a prefix on a field name produces a qualified field name. The context vari 
able must be the first prefix added to a field name. 


A.1.2.2 Other Field Name Qualifiers -- Using other qualifiers as prefixes to 
field names is the second method of overriding DATATRIEVE’s default mecha- 
nism of name recognition. 


Although DATATRIEVE does not require that each field name be unique, each 
fully qualified field name must be unique. The fully qualified field name consists c 
the domain name, the top-level group field name, the names of any group field to 
which the elementary field belongs, and the elementary field name. You must sey 
arate each element of the fully qualified name from the next with a period. 


For example, in the domain YACHTS, the fully qualified field name of MODEL 
is: 


YACHTS .BOAT. TYPE .MODEL 


You can use these elements in any combination that preserves their hierarchical 
order to distinguish the MODEL field in YACHTS from the MODEL field in 
another domain, such as OWNERS. 


When DATATRIEVE encounters a qualified field name, it searches the context 
stack for the first match of the name you specify. For example, if you use 
BOAT.MODEL in a record selection expression, DATATRIEVE searches the 
context stack for the first valid occurrence of the name BOAT and searches the 
branches of the hierarchy under BOAT for the first valid occurrence of the name 
MODEL. 


The success of the search is not jeopardized because you omit the group field 
name TYPE from the qualified name of MODEL. DATATRIEVE searches the 
entire hierarchy under BOAT until it finds the first valid occurrence of TYPE. 
When an intermediary group field name is omitted, DATATRIEVE searches the 
hierarchy according to the order in which the fields of the record were defined. 


Fully qualified field names are adequate when working with two or more domain 
that share elementary or group field names, or both. However, when you work 
with two record streams from the same domain, you must further qualify the fie 
name with a context variable. This extra qualification is especially necessary wh 
dealing with lists in hierarchical records. 
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tuppose you want to display information about all builders who build boats with 
1ore than one type of rig. YACHT is the given name of the record associated 
ith the domain YACHTS. The field tree of YACHT has the structure: 


ACHTS 
01 BOAT 

03 TYPE 
06 MANUFACTURER 
06 MODEL 

03 SPECIFICATIONS 
06 RIG 
06 LENGTH_OVER_ALL 
06 DISPLACEMENT 
06 BEAM 
06 PRICE 


ou can print the desired information with nested FOR loops. For each boat from 
1e outer FOR statement, you want DATATRIEVE to loop through all the boats 
id find all the ones with the same builder. For each one it finds, you want it to 
ympare its rig with the rig of the boat from the outer loop. Then you want to sep- 
‘ate the ones for which the rigs are not the same. At first, you might be tempted 
» use the following statement to produce the desired list: 


"R> SET NO PROMPT ~ 
‘R> FOR YACHTS 


IN> FOR YACHTS WITH BUILDER = BUILDER AND 
IN> RIG NE RIG . 
He PRINT BUILDER, RIG, RIG 

"R> me 


fter a long search for records, DATATRIEVE displays no records. The problem 
that the syntax above asks DATATRIEVE to look for a boat with a rig that is 
»t equal to itself -- an obvious contradiction. Both of the fields named RIG 

solve to the record stream formed by the second FOR statement. The name 
UILDER also resolves to the same record stream. 


hat happens when you enter the above statement is that DATATRIEVE takes 
e first record from YACHTS but does not look at any of the values in its fields. 
1en it looks at every record in YACHTS and discovers that for every one of 
em. the name of the builder equals itself, but that no rig is not equal to itself. 
lus every record in YACHTS fails to meet the condition set by the statement. 


ATATRIEVE then takes the second record in YACHTS and once again goes 
rough all the boats. finding that the two values are always equal to themselves 
d thus fail to meet the impossible demands of the statement. And so it goes for 
ch record: two comparisons for 113 times 113 records, and no records meet the 
lf-contradictory conditions. 
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The problem is how to get DATATRIEVE to look at the builder and rig of the 
outer FOR statement when making the comparison. The context variable pro- 
vides one solution: 


DTR> FOR A IN YACHTS . 
CON> FOR YACHTS WITH BUILDER = A.BUILDER AND RIG NE A.RIG 
CON> PRINT BUILDER, A.RIG, RIG 


MANUFACTURER RIG RIG 
AMERICAN SLOOP MS 


AMERICAN MS SLOOP 
CHALLENGER SLOOP KETCH 


PEARSON KETCH SLOOP 
PEARSON KETCH SLOOP 
DTR> 


In this case, the use of the context variable A forces DATATRIEVE to look to th 
record stream formed by the outer FOR statement. At the same time, 
DATATRIEVE recognizes the unqualified names, RIG and BUILDER. in the 
context established by the most recent RSE: the one in the second FOR state- 
ment. The conditions in the second FOR statement are no longer impossible. anc 
information from 62 records is displayed. 


The way DATATRIEVE treats the unqualified names in this example illustrates 
another rule for context resolution: the left-hand member of a Boolean expressio 
must resolve to the record selection expression of which it is a part. If you start 
the Boolean in the second FOR statement with A,BUILDER, DATATRIEVE 
tells you that A,BUILDER is undefined or used out of context. 


You can add a second context variable in the above example to make sure the re 


olution of the names is explicitly stated: 


DTR> FOR A IN YACHTS 
CON> FOR B IN YACHTS WITH B.BUILDER = A.BUILDER AND B.RIG NE A.RIG 
CON> PRINT B.BUILDER, A.RIG, B.RIG 
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ou gain two advantages by specifying the second context variable: clarity of 
‘presentation and the certainty of getting an error message from DATATRIEVE 
you make a syntax error. Using the second context variable, however, does not 


low you to violate the rule for resolving field names on the left side of Boolean 
<pressions. 


.1.2.3 The Effect of the CROSS Clause on Name Recognition -- You can use 
ie CROSS clause of the record selection expression to produce the same record 
ream as the nested FOR statements in the previous example. The CROSS 

ause, however, is not constrained by the rule for resolving field names on the 

ft side of Boolean expressions. 


‘ith the CROSS clause, you can establish more than one context variable (and, 
nce, more than one context block) in a record selection expression. This is the 
mtax of the CROSS clause: 


ROSS [context-var IN] rse-source [OVER field-name]] [...] 
1e format for rse-source is: 


domain-name 
collection-name 


list 

rdb-relation-name 

dbms-record-name MEMBER 
OWNER [OF] [context-name.set-name] 
WITHIN 


ATATRIEVE creates a context block for each source in the CROSS clause. The 
mes in all such context blocks resolve to the same record selection expression. 
nsequently. adequately qualified names in the Booleans of the record selection 


pression can appear on either the right-hand or left-hand side of any of the 
oleans. 
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For example, any of the following statements produces the same result as the 
nested FOR statements of the previous example: 


DTR> FOR A IN YACHTS CROSS B IN YACHTS WITH 


CON> B.BUILDER = A.BUILDER AND B.RIG NE A.RIG 
CON> PRINT B.BUILDER, A.RIG, B.RIG 

DTR> FOR A IN YACHTS CROSS B IN YACHTS WITH 

CON> A.BUILDER = B.BUILDER AND A.RIG NE B.RIG 
‘CON> PRINT B.BUILDER, A.RIG, B.RIG 

DTR> FOR A IN YACHTS CROSS YACHTS WITH 

CON> BUILDER = A.BUILDER AND RIG NE A.RIG 
CON> ' PRINT BUILDER, A.RIG, RIG 

DTR> FOR A IN YACHTS CROSS YACHTS WITH 

CON> A.BUILDER = BUILDER AND A.RIG NE RIG 
CON> PRINT BUILDER, A.RIG, RIG 


In cases where the sources specified in the CROSS clause share a field name, you 
can use the OVER clause to simplify the context specification. The field name 
specified in the OVER clause must exist in the records of all the sources specifier 
in the CROSS clause. The following two statements are equivalent to the preced- 
ing ones: 


DTR> FOR A IN YACHTS CROSS YACHTS OVER BUILDER WITH 
CON> RIG NE A.RIG 
CON> PRINT BUILDER, A.RIG, RIG 


DTR> FOR A IN YACHTS CROSS YACHTS OVER BUILDER WITH 
CON> A.RIG NE RIG 
CON> PRINT BUILDER, A.RIG, RIG 


To resolve field names in a record selection expression containing a CROSS 
clause, DATATRIEVE looks first at the context block for the last source specific 
in the CROSS clause. If that block contains no match for the field name, it begir 
looking at the context blocks for the other sources, working its way toward the 
block for the first source in the clause. 


Consequently. when referring to fields from two or more identical sources, only 
those fields from the last source in the CROSS clause can remain unqualified. Ir 
such cases, you must use context variables to establish the appropriate context 
for fields from the other sources in the clause. 


A.1.3. The Left Context Stack for Assignment Statements 


When you make assignment statements at DATATRIEVE command level or as 
part of STORE or MODIFY statements, DATATRIEVE must assign values to 
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ie field or variable you intend. It uses the left context stack to associate the val- 
26 you supply with the fields and variables you want the values assigned to. 
locks on the left context stack are for records and variables that you can update. 


Thenever DATATRIEVE begins to process a statement, the left context stack 
mtains the global variables you have declared and not released. Any local 
iriables you declare in compound statements are also on the left context stack. 


1e local variables are removed when the statement in which you declared them 
ids. . 


»cal and global variables are on both stacks. Each type of variable has a value 
at can be assigned to a field or another variable: hence, they are on the right 
ntext stack. Both can be updated with new values you assign them; hence, they 
eon the left context stack. 


mtext blocks for a record you want to modify are also on both context stacks. 
ie record has a value you can use in Boolean expressions and assignment state- 
ants, and ina MODIFY statement you can update that value. Because a field is 

both stacks at the same time, you can use the old value of the field to calculate 
e new value. You can use the following form of assignment statement: 


: MODIFY USING PRICE = PRICE * 1.1 
> 


\TATRIEVE retrieves the old value of PRICE associated with the name on the 
‘ht context stack and multiplies the old PRICE by a constant. It then associates 


at value with the name PRICE on the left context stack and updates the value 
the PRICE field. 


zen you enter a STORE statement, the only context block for the new record is 
the left context stack. No record exists yet, and, of course, no values are asso- 
ted with its fields. The fields can only receive values. 


wever, as soon as DATATRIEVE associates a value with a field, you can move 
it value to the right context stack and use it on the right side of assignment 
tements. You can make this shift before you finish assigning values to all the 
‘ds of the new record. In fact. you can use the values of new fields to calculate 

: values DATATRIEVE stores in other new fields in the same record. 


shift newly stored values to the right context stack, you include a context vari- 


e with the domain name when you enter the STORE statement: 


> STORE A IN YACHTS USING . 
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Then, in the USING clause, you use the context variable to qualify the names of 
any field whose value you want to use on the right side of an assignment 
statement: 


DTR> STORE A IN YACHTS USING 


CON> BEGIN 

CON> Fi = value-expression 
CON> F2 = value-expression 
CON> F3 = A.Fi +. A.F2 

CON> END 

DTR> 


The context variable allows you to associate a field name on the right context 
stack with its new value as soon as you assign the value to the field. You cannot, 
however, use a field name on the right side of an assignment statement until you 
have assigned a value to the field. 


You can combine STORE and MODIFY statements to keep an audit trail of 
changes made to records in a domain and to change statistical records when you 
store new records. 


To form an audit trail, you need a domain for the audit records. This domain can 
use the same record definition as the original domain, but it must have its own 
domain definition and its own data file. Here is a simple example: 


DTR> SHOW AUDIT_YACHTS 
DOMAIN AUDIT_YACHTS USING 
YACHT ON AUD_YACHT; 
DTR> FOR A IN YACHTS MODIFY USING 
CON> BEGIN 


CON> BUILDER = *.BUILDER 
CON> MODEL = *.MODEL 
CON> RIG = *. RIG 
CON> LOA = *, LOA 
CON> DISP = * , WEIGHT 
CON> BEAM = *, BEAM 
CON> PRICE =  *.PRICE 


CON> STORE B IN AUDIT_YACHTS USING 
CON> B.BOAT = A.BOAT 

CON> END 

Enter BUILDER: 


If you have a VERIFY USING clause in the MODIFY statement, you should pt 
the STORE statement as the last statement in the VERIFY clause. If you put t 
VERIFY clause after the STORE statement and the VERIFY clause aborts the 
change, you have a record of the change, but you have not changed the record. 
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yu can also embed a MODIFY statement in a STORE statement. In this exam- 
2, the embedded MODIFY statement updates a record of the last date a new 
cord was added to the data file and records the TYPE field of the record stored. 
1e file LAST.DAT is a sequential file with one record in it. 


R> SHOW LAST_ENTRY 

MAIN LAST_ENTRY USING LAST_REC ON LAST.DAT; 
R> SHOW LAST_REC 

CORD LAST_REC USING 

TOP. 

LAST_DATE USAGE DATE. 

TYPE PIC X(20). 


%> STORE A IN YACHTS USING 

\> BEGIN 

V> BUILDER = *.BUILDER 

> MODEL = *.MODEL 

\> RIG = *.RIG 

\> LOA = *.LOA 

> DISP = *.DISP 

I> BEAM = *.BEAM 

I> PRICE = *.PRICE 

|> MODIFY B IN LAST_ENTRY USING 


|> BEGIN 

I> LAST_DATE = "TODAY" 
I> B.TYPE = A.TYPE 

I> END 

I> END 

ier BUILDER: 


th the proper use of context variables, you can also store or change data in 
ds shared by two or more domains. 


2 Single Record Context 


2 DATATRIEVE statements PRINT, MODIFY, and ERASE can act on one 
ord at a time or on an entire record stream or collection. The records on which 


y act are called target records. You can identify target records for these state- 
nts in four ways: 


A SELECT statement identifies one target record in a collection. 


The keyword ALL in a statement. without an OF rse clause, makes all 
records in a collection the targets of the statement. 


An OF rse clause in the statement forms a target record stream. 


The RSE clause in a FOR statement forms a stream of target records for the 
statement contained in the FOR loop. 
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A.2.1. The SELECT Statement and the Single Record Context 


Before discussing the SELECT statement and context, a short review of facts 
about collections is in order. 


~ DATATRIEVE keeps a list of the collections you form with the FIND statement 
The most recent one formed is always at the top of the list and is called the 
CURRENT collection. The only other collections on the list are the ones to whic 
you assign a name when you form them. If you do not assign a name to the 
CURRENT collection, the next collection you form becomes the new CURREN'’ 
collection. DATATRIEVE discards the old CURRENT collection unless you give 
it aname when you form it. 


With the RELEASE command, you can remove a collection from that list. If you 
release the CURRENT collection, the next one on the list becomes the 
CURRENT collection. 


No collection on this list, however, is represented by a block on the context stac. 
unless you use the SELECT statement to single out one record in the collection 
When you select a record in a collection, DATATRIEVE puts a block for that 
collection on the context stack. If every existing collection has a selected 
record, then DATATRIEVE keeps a block on the context stack for each of thos¢ 
collections. 


The relative ages of the collections with selected records determine the order of 
context blocks for collections. The “oldest” collection with a selected record is t. 
bottom of the context stack. Because the CURRENT collection is always the 
“youngest,” its context block, if it has one, is nearest the top. 


This order of context blocks for collections establishes the order DATATRIEVE 
uses not only for recognizing field names, as described above, but also for identi 
fying single target records. When you enter the most abbreviated forms of the 
PRINT, MODIFY, and ERASE statements, DATATRIEVE looks on the conte: 
stack for the first valid single record context to carry out the specified action. It 
looks for the “youngest” collection with a selected record and either prints the 
record, erases it, or changes it. 


The following sequence of examples illustrates the effect of he SELECT and 
DROP statements on single record context and the subsequent actions of the 
PRINT, MODIFY, and ERASE statements. 
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rm a collection of records from the YACHTS domain, call it BIGGIES, select 
> third record as the target record, and display it: 


t> READY YACHTS WRITE 
i> FIND BIGGIES IN YACHTS WITH LOA > 40 
records found] 


t> SELECT 3 
t> PRINT 
LENGTH 
OVER 
IJUFACTURER MODEL RIG ALL WEIGHT BEAM PRICE 
ILFSTAR 41 KETCH 41 22,000 12 $41,350 


> 


re a new record in the YACHTS domain and form a collection that consists of 
it one record. Later. you can modify and erase this record: 


> STORE YACHTS 

.er MANUFACTURER: HINKLEY 

er MODEL: BERMUDA 40 

er RIG: YAWL 

er LENGTH_OVER_ALL: 40 

er DISPLACEMENT: 20000 

er BEAM: 12 

er PRICE: 82,000 

> FIND YACHTS WITH BUILDER = "HINKLEY" 


record found] 
> 


1 now have two collections, CURRENT (the younger) and BIGGIES (the 
er): 


> SHOW COLLECTIONS 
lections: 
CURRENT 
BIGGIES 


> SHOW CURRENT 
lection CURRENT 
Domain: YACHTS 
Number of Records: i 
No Selected Record 

> SHOW BIGGIES 
lection BIGGIES 
Domain: YACHTS 
Number of Records: 8 


Selected Record: 3 
> 
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The CURRENT collection has no selected record, but BIGGIES still does. 
Consequently, when you type PRINT and press the RETURN key again, 
DATATRIEVE prints the record in the first valid single record context, that is, 
the selected record in BIGGIES: 


DTR> PRINT 
LENGTH 
OVER 
MANUFACTURER MODEL RIG ALL WEIGHT BEAM PRICE 
GULFSTAR Ai KETCH 41 22,000 12 $41,350 
DTR> 


When you type SELECT and press the RETURN key, DATATRIEVE selects tl 
first and only record in the CURRENT collection. Now when you type PRINT a: 
press the RETURN key, the single record context has changed. Now the selecte 
record in the CURRENT collection is the target record of the PRINT statement 


DTR> SELECT 


DTR> PRINT 
LENGTH 
OVER 
MANUFACTURER MODEI. RIG ALL WEIGHT BEAM PRICE 


HINKLEY BERMUDA 40 YAWL 40 20,000 12 $82,000 


DTR> SHOW CURRENT 

Collection CURRENT 
Domain: YACHTS 
Number of Records: i 
Selected Record: i 


Now modify the price of the target record and display the result. The MODIFY 
and PRINT statements both act on the record in the first valid single record co 
text, that is, the selected record in the CURRENT collection: 


DTR> MODIFY PRICE 
Enter PRICE: 75,000 


DTR> PRINT 
LENGTH 
OVER 
MANUFACTURER MODEL RIG ALL WEIGHT BEAM PRICE 
HINKLEY . BERMUDA 40 YAWL 40 20,000 12 $75,000 
DTR> 
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ow type ERASE and press the RETURN key. The ERASE statement also acts 
1 the record in the first valid single record context, and the record for the 
INKLEY boat is removed from the data file YACHT.DAT. Even though you 
‘ase the only record in the collection, DATATRIEVE does not discard the collec- 
on. It takes note that you have erased the selected record and removes the con- 
xt block for the CURRENT collection from the context stack. You can verify 

ie change in single record context by typing PRINT and pressing RETURN. 

ne selected record from BIGGIES is again in the first valid single record 

mtext: 


‘R> ERASE 

R> SHOW CURRENT 

llection CURRENT 
Domain: YACHTS 
Number of Records: 1 
Selected Record: 1 (Erased) 


R> PRINT 

LENGTH 

OVER 
NUFACTURER MODEL RIG ALL WEIGHT BEAM PRICE 
ULFSTAR 41 KETCH 41 22,000 12 $41,350 


R> 


you type MODIFY or ERASE and press the RETURN key, and no existing 
llection has a selected record, DATATRIEVE displays a message that there is 
target record for the action you propose: 


R> ERASE . 
target record for ERASE. 
R> MODIFY 

target record for MODIFY. 
R> 


»wever, if you type PRINT and press the RETURN key, and no existing collec- 
m has a selected record, DATATRIEVE displays a message that there is no 
lected record and then prints out the whole collection: 


R> FIND YACHTS WITH BUILDER = "ALBIN" 
records found 

R> PRINT 

record selected, printing whole collection 


(continued on next page) 
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LENGTH 
OVER 
MANUFACTURER MODEL RIG ALL WEIGHT BEAM PRICE 


ALBIN 79 SLOOP 26 4,200 10 $17,900 
ALBIN BALLAD SLOOP 30 7.276 10 $27,500 
ALBIN VEGA SLOOP 27 5070 08 $18,600 
DTR> | 


You can change the single record context with the DROP statement. The DROP 
statement removes the selected record from a collection but does not erase the 
record from the data file. When you type DROP and press the RETURN key, an 
the CURRENT collection has no selected record, DATATRIEVE ceplays a mes- 
sage on your terminal: 


DTR> FIND BIGGIES IN YACHTS WITH LOA > 40 
[8 records found] 

DTR> DROP 

No collection with selected record for DROP. 


If the CURRENT collection has a selected record, the DROP statement removes 
that record from the collection when you type DROP and press the RETURN 
key. If other collections have selected records, you must specify the collection 
name in the DROP statement. 


The CURRENT collection is BIGGIES. Select and display the first record in 
BIGGIES and form a new CURRENT collection of boats built by Albin: 


DTR> SELECT; PRINT 


LENGTH 

OVER 
MANUFACTURER MODEL RIG ALL WEIGHT BEAM PRICE 
CHALLENGER 41 KETCH 41 26,700 13 $51,228 


DTR> FIND YACHTS WITH BUILDER = "ALBIN" 
[3 records found] 
DTR> 


Now select. display, and drop the first record of the CURRENT collection. Then 
enter a SHOW CURRENT command to see how DATATRIEVE records the 
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sults of your actions. The SELECT creates a single record context for the cur- 
nt collection, thus the target record of the PRINT statement is the selected 
cord in the CURRENT collection, not in BIGGIES: 


R> SELECT 
R> PRINT 
LENGTH 
OVER 
NUFACTURER MODEL RIG ALL WEIGHT BEAM PRICE 
LBIN 79 SLOOP 26 4,200 10 $17,900 
R> DROP 


R> SHOW CURRENT 
llection CURRENT 
Domain: YACHTS 
Number of Records: 3 
Selected Record: 1 (Dropped) 
R> 


hen you drop a selected record from a collection, you change the single record 
ntext. The context block for that collection is removed from the context stack. 


msequently, when you type PRINT and press the RETURN key again, 
\TATRIEVE displays the selected record in BIGGIES, the record in the first 
lid single record context: 


> PRINT 
| LENGTH 
OVER 
IUFACTURER MODEL RIG ALL WEIGHT BEAM PRICE 
IALLENGER 41 KETCH 41 26,700 13 $51,228 


> 


like PRINT, MODIFY, and ERASE, the DROP statement does not act on the 
ord in the first valid single record context. You have already dropped the 
ected record in the CURRENT collection. When you type DROP and press the 
'TURN key again, DATATRIEVE displays a message on your terminal and 

*s not drop the selected record in BIGGIES. Because BIGGIES is not the 
‘RRENT collection, you have to specify its name in the DROP statement: 


> DROP 
get record has already been dropped. 
> DROP BIGGIES 
> SHOW BIGGIES 
lection BIGGIES 
Domain: YACHTS 
Number of Records: 8 
Selected Record: 1 (Dropped) 
> 
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Now you have no valid single record context. When you type PRINT and press 
RETURN, DATATRIEVE displays the whole CURRENT collection because ther 
is no selected record in either of the two existing collections. Because you droppe 
one record from the CURRENT collection, it contains only two records now: 


DTR> PRINT 
No record selected, printing whole collection 

LENGTH 

OVER 

MANUFACTURER MODEL RIG ALL WEIGHT BEAM PRICE 
ALBIN BALLAD SLOOP 30 7,276.10 $27,500 
ALBIN VEGA SLOOP 27 5,070 08 $18,600 
DTR> 


To show that you have not erased the record dropped from the CURRENT collec 
tion, form and display a new CURRENT collection of boats by Albin: 


DTR> FIND YACHTS WITH BUILDER = "ALBIN" 
[3 records found 
DTR> PRINT ALL 


LENGTH 
OVER 
MANUFACTURER MODEL RIG ALL WEIGHT BEAM PRICE 
ALBIN 79 SLOOP 26 4,200 10 $17,900 
ALBIN BALLAD SLOOP 30 7,276 10 $27,500 
ALBIN VEGA | SLOOP 27 5,070 08 $18,600 


DTR> 


A.2.2 The CURRENT Collection as Target Record Stream 


The preceding example shows the effect of the keyword ALL on a PRINT state- 
ment that does not contain an OF rse clause. 


Although DATATRIEVE acts on only one record at a time, you can identify moi 
than one record for a single DATATRIEVE statement to act on. With the 
keyword ALL, you can make every record in the CURRENT collection the targe 
of a single PRINT, MODIFY, or ERASE statement. Such a statement, however: 
cannot also contain an OF rse clause. 


If you have a CURRENT collection and type PRINT ALL and press the 
RETURN key, DATATRIEVE displays the whole CURRENT collection. If you 
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ave no CURRENT collection, DATATRIEVE displays a message on your termi- 


ial. To illustrate this effect, release all collections and enter the statement 
"RINT ALL: 


TR> SHOW COLLECTIONS 
ollections: 
CURRENT 
BIGGIES 


TR> RELEASE CURRENT, BIGGIES 
TR> SHOW COLLECTIONS 

o established collections. 
TR> PRINT ALL 


current collection has not been established. 
.[R> 


\ATATRIEVE displays the same message on your terminal when you have no 


URRENT collection and you enter either an ERASE ALL or MODIFY ALL 
vatement. 


Then you have a CURRENT collection and you enter an ERASE ALL state- 
ient, DATATRIEVE removes every record in the CURRENT collection from the 


ata file. Although frequently useful, this operation can jeopardize valuable data if 
yu use it carelessly. 


he various forms of the MODIFY ALL statement change the data in each record 
‘the CURRENT collection. (See the article on the MODIFY statement in the 
AX DATATRIEVE Reference Manual.) Make a collection of the first three 
ichts with no listed price. Display the CURRENT collection, modify the PRICE 

' $30,000, display the results of the change, and change the price back to zero 
sing a different form of the MODIFY ALL statement: 


‘R> FIND FIRST 3 YACHTS WITH PRICE = O 
' records found] 
‘R> PRINT ALL 


LENGTH 

OVER 
NUFACTURER MODEL RIG ALL WEIGHT BEAM PRICE 
LOCK I. 40 SLOOP 39 18,500 12 
UCCANEER 270 SLOOP 27 5,000 08 
UCCANEER 320 SLOOP 32 12,500 10 
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DTR> MODIFY ALL PRICE 
Enter PRICE: 30,000 
DTR> PRINT ALL 


LENGTH 
OVER 
MANUFACTURER MODEL RIG ALL WEIGHT BEAM PRICE 
BLOCK [. 40 SLOOP 39 18,500 12 $30,000 
BUCCANEER 270 SLOOP 27 5,000 08 $30,000 
BUCCANEER 320 SLOOP 32 12,500 10 $30,000 


DTR> MODIFY ALL USING PRICE = 0; PRINT ALL 


LENGTH 
OVER 
MANUFACTURER MODEL RIG ALL WEIGHT BEAM PRICE 
BLOCK I. 40 SLOOP 39 18,500 12 
BUCCANEER 270 SLOOP 27 5,000 08 
BUCCANEER 320 SLOOP 32 12,500 10 


DTR> 


If your collection contains many records and you mistakenly enter an ERASE 
ALL or MODIFY ALL statement, you can enter a CTRLI/C to prevent all the 
records in the CURRENT collection from being erased or changed. How many 
records get erased or changed under such circumstances depends on the speed 
with which you enter the CTRL/C, the processing load on your system, and the 
priority of your process. 


A.2.3. The OF rse Clause and Target Record Streams 


The OF rse clause in a PRINT, ERASE, or MODIFY statement lets you create a 
new context for that statement. The OF rse clause specifies a target record | 
stream that overrides any context established for your existing collections. For 
each such OF rse clause, DATATRIEVE puts a new block on the context stack. 
When DATATRIEVE completes execution of the statement, it removes that 
block from the context stack. 


The following example contrasts the effect of PRINT, PRINT ALL, and PRINT 
OF rse. (When the PRINT statement does not include a list of fields, you can om: 
the OF from the statement.) The record selection expression here is FIRST 3 
YACHTS WITH PRICE = 0. This RSE identifies a new target record stream fo! 
the PRINT statement that overrides the CURRENT collection as a target record 
stream. It also overrides the single record context of the selected record in the 
CURRENT collection: 


DTR> FIND FIRST 3 YACHTS 
[3 records found] 
DTR> SELECT; PRINT 
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LENGTH 


OVER 
ANUFACTURER MODEL RIG ALL WEIGHT BEAM PRICE 
ALBERG 37 MK II KETCH 37 20,000 12 $36,951 
[R> PRINT ALL | 

LENGTH 

OVER 
\NUFACTURER MODEL RIG ALL WEIGHT BEAM PRICE 
\LBERG 37 MK II KETCH 37 20,000 12 $36,951 
\LBIN 79 - gLooP 26 4°200 10 $17,900 
\LBIN BALLAD SLOOP 30 7.276 10 $27,500 


[R> PRINT FIRST 3 YACHTS WITH PRICE = 0 


LENGTH 

| OVER 
\NUFACTURER MODEL RIG ALL WEIGHT BEAM PRICE 
SLOCK I. 40 SLOOP 39 18,500 12 
SUCCANEER 270 SLOOP 27 5,000 08 
SUCCANEER 320 SLOOP 32 12,500 10 


"R> 


9 reduce the risk to your data, DATATRIEVE forces you to include both 
»ywords ALL and OF when using the OF rse clause in MODIFY and ERASE 
atements. Although the results are not shown here, you must type MODIFY 

id ERASE statements to resemble the following examples. The record selection 
:pression used in these statements is PHONES WITH DEPT = "32T": 


DIFY ALL OF PHONES WITH DEPT = "32T" 
DIFY ALL DEPT OF PHONES WITH DEPT = "32T" 
DIFY ALL USING DEPT = *."NEW DEPT" OF PHONES WITH DEPT = "32T" 


ASE ALL OF PHONES WITH DEPT = "32T" 


nless you include assignment statements in the USING clause of a MODIFY 
atement. DATATRIEVE prompts you once to supply a value for each elemen- 
ry field specified or implied in the statement. After you respond to the last of 
e prompts, DATATRIEVE begins to change each of the records in the 
JRRENT collection to correspond to the values you supplied to the prompts. 
yu Can prevent any changes from taking effect by entering CTRL/Z when 
sponding to any of the prompts. 
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A.2.4 FOR Statements and Target Record Streams 


You can use FOR statements to create target record streams for the 
DATATRIEVE statements that use single record context. Using FOR loops has 
an advantage over using target record streams formed by OF rse clause and the 
target record stream formed of the CURRENT collection by the keyword ALL. 
The FOR statement lets you work with each record individually; you do not have 
to perform the same operation on all target records. By putting STORE and 
MODIFY statements and prompting value expressions in a FOR loop, you can ac 
on each member of a record stream or collection one at a time. 


When you put a MODIFY statement in a FOR statement, DATATRIEVE 
prompts you once for each field in the record if you do not specify a field list or a 
USING clause in the MODIFY statement. 


This FOR statement creates a record stream of boats that have no price listed. 
The MODIFY statement prompts you to supply a price for each record in the 
record stream. You can put a unique value in the PRICE field for each boat: 


DTR>READY YACHTS MODIFY 

DTR>FOR YACHTS WITH PRICE MISSING MODIFY PRICE 
Enter PRICE: 12900 

Enter PRICE: 15600 

Enter PRICE: 


Another valuable feature of FOR loops is the complex relationships you create 
between record streams when you include one FOR loop inside another. Each 
FOR statement puts a block on the context stack. As a result, you can use the 
context mechanism to transfer values between records. 


By putting a MODIFY statement inside two FOR statements, you can automati- 
cally update master records with the data from periodic transaction records: 


DTR> FOR A IN DAILY_TRANSACTIONS 
CON> FOR B IN MASTER_DATA WITH B.ACCOUNT = A. ACCOUNT 
CON> MODIFY USING 


CON> BEGIN 

CON> MASTER_BAL = MASTER_BAL - WITHDRAW + DEPOSIT 
CON> TOT_WITHDRAW = TOT_WITHDRAW + WITHDRAW 

CON> TOT_DEPOSIT = TOT_DEPOSIT + DEPOSIT 

CON> END 

DTR> 


The Boolean expression in this example limits the record stream for the inner 
FOR statement to one record. 


You can also create nested FOR statements in which DATATRIEVE executes a 
series of statements at each level of nesting. For each owner record in the next 
example, DATATRIEVE asks you if you want to modify the SPECS field of eve: 
boat in the YACHTS inventory built by the manufacturer of the owner’s boat. 
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‘he third time through the outer loop, DATATRIEVE again begins the cycle of 


rompting for the boats by Albin, because the third person in the OWNERS 


omain also owns a boat by Albin. Notice that the record changed during the sec- 
nd loop appears during the third: 


[R>FOR OWNERS 
JN> BEGIN 


)N> PRINT SKIP, BUILDER, SKIP 
JN> FOR YACHTS WITH BOAT.BUILDER = OWNER.BUILDER 


JN> BEGIN 


)N> PRINT SPECS 
IN> IF *."DO YOU WANT TO CHANGE THIS" CONT "Y" 
)N> THEN MODIFY SPECS 


)N> END 
JN> END 


3UTLDER 
BERG 


LENGTH 
OVER 
IG ALL WEIGHT 


‘TCH 37 20 ,000 
iter DO YOU WANT TO 


BIN 


OOP 26 4,200 
ter DO YOU WANT TO 
OOP 30 7,276 
ter DO YOU WANT TO 
OOP 27 § ,070 
ter DO YOU WANT TO 
ter RIG: KETCH 


BEAM PRICE 


12 $36,000 
CHANGE THIS: N 


10 $17,900 
CHANGE THIS: N 
10 $27,500 

CHANGE THIS: 
08 $18,600 
CHANGE THIS: Y 


ter LENGTH_OVER_ALL: 35 


ter DISPLACEMENT: 
ter BEAM: 12 
ter PRICE: 33000 


BIN 


OOP 26 4,200 
ter DO YOU WANT TO 
DOP 30 7,276 
ter DO YOU WANT TO 
TCH 35 17 ,000 
ter DO YOU WANT TO 


+ 
JOP 31 


8,650 
ter DO YOU WANT TO 
scution terminated 
i> 


17000 


10 $17,900 
CHANGE THIS: N 
10 $27,500 
CHANGE THIS: N 
12 $33,000 
CHANGE THIS: N 


09 
CHANGE THIS: “~Z 
by operator 
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Sample Database Definitions and Procedures B 


his appendix contains: 


Record and domain definitions used in the sample databases that come with 
the VAX DATATRIEVE software. 


Table and view definitions that use or supplement those domains. 


Procedures that use the sample databases. 


Rdb and DBMS data definitions and procedures used in the DATATRIEVE 
UETP, the User Environment Test Package. 


1 


RMS Data Definitions and Procedures 


CORD ANNUAL_REC 
A 


DATE DATE PIC YYYY. . 

EQUIPMENT_SALES REAL EDIT_STRING 2229.9. 

SERVICES REAL EDIT_STRING 229.9. 

REVENUE COMPUTED BY EQUIPMENT_ See + SERVICES EDIT_STRING 2229.9. 
NET_INCOME REAL EDIT_STRING 2Z9.9 

NET_INCOME_PER_SHARE REAL EDIT_ STRING Z29.9. 

RESEARCH REAL QUERY_NAME DEVELOPMENT EDIT_STRING ZZ9.9. 
INVENTORIES REAL EDIT_STRING ZZ9.9. 

EMPLOYEES REAL EDIT_STRING IS ZZ,ZZZ. 

FILLER PIC X(68). 


MAIN ANNUAL_REPORT USING ANNUAL_REC ON DTR$LIBRARY: ANNUAL.DAT; 


B-1 


! 

' 

PROCEDURE BILL_PAID 

READY PAYABLES SHARED READ 

REPORT PAYABLES WITH BILL_PAID MISSING AND 
ITEMS_RECEIVED NOT MISSING AND 
INVOICE_DUE NOT MISSING SORTED BY INVOICE_DUE 

SET REPORT_NAME = “Accounts Payable" 

SET COLUMNS_PAGE = 65 

PRINT RUNNING COUNT ("COUNT"), MANUFACTURER, 
ITEMS_RECEIVED, INVOICE_DUE, BILL_PAID, WHSLE_PRICE, 
COL 55,RUNNING TOTAL WHSLE_PRICE ("TOTAL"/"OWNED") USING $$$,$$$ 

END_REPORT 

END-PROCEDURE 


1 

] 

PROCEDURE BILL_PAID_1 

READY PAYABLES SHARED READ 

REPORT PAYABLES WITH BILL_PAID MISSING AND 
ITEMS_RECEIVED NOT MISSING AND 
INVOICE_DUE NOT MISSING SORTED BY INVOICE_DUE 

SET REPORT_NAME = "Accounts Payable" 

SET COLUMNS_PAGE = 65 

PRINT RUNNING COUNT ('COUNT") , MANUFACTURER, 
ITEMS_RECEIVED , INVOICE_DUE, BILL_PAID , WHSLE_PRICE, 
RUNNING TOTAL WHSLE_PRICE ("TOTAL"/"OWNED") USING $$$, $$$ 

END_REPORT 

END-PROCEDURE 


! 

! 

DOMAIN FAMILIES 

USING FAMILY_REC ON DTR$LIBRARY: FAMILY. DAT; 


' 
RECORD FAMILY_REC 
O1 FAMILY. 
03 PARENTS. 
06 FATHER PIC X(10). 
O06 MOTHER PIC X(10). 
03 NUMBER_KIDS PIC 99 EDIT_STRING IS 29. 
03 KIDS OCCURS 0 TO 10 TIMES DEPENDING ON NUMBER_KIDS. 
O6 EACH_KID. 
O09 KID_NAME PIC X(10) QUERY_NAME IS KID. 
09 AGE PIC 99 EDIT_STRING IS Z9. 


' 
DOMAIN KETCHES 
OF YACHTS BY 
01 KETCH OCCURS FOR YACHTS WITH RIG EQ "KETCH". 
03 TYPE FROM YACHTS. 
03 LOA FROM YACHTS. 
03 PRICE FROM YACHTS. 
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{OCEDURE LOA_REPORT 
‘PORT ON *.FILE 
SET REPORT_NAME="JIM’S VERY OWN LISTING"/"OF"/"INTERESTING SAILBOATS" / 
~ "(BY LENGTH)" 
SET LINES_PAGE=55, COLUMNS_PAGE=72 
AT TOP OF LOA PRINT LOA("LENGTH") 
PRINT TYPE, RIG, DISP, BEAM USING Z9 , PRICE 
AT BOTTOM OF LOA PRINT SKIP, COL 32, "*** AVERAGE ***", 
AVERAGE DISP, AVERAGE BEAM, AVERAGE PRICE 
AT BOTTOM OF REPORT PRINT SKIP, "REPORT AVERAGES", 
AVERAGE DISP, AVERAGE BEAM, AVERAGE PRICE | 
AT BOTTOM OF PAGE PRINT SKIP, COL 20, 
"""ANOTHER SERVICE OF QUERY ENTERPRISES""" 
D_REPORT . 
D-PROCEDURE 


MAIN OWNERS 
SING OWNER_RECORD ON OWNER. DAT; 


MAIN OWNERS_SEQUENTIAL USING OWNER_RECORD ON DTR$LIBRARY : OWNER. SEQ; 


CORD OWNER_RECORD 
OWNER. 
03 NAME PIC X(10) QUERY_HEADER IS "OWNER"/"NAME" 
EDIT_STRING IS X(5). : 
03 BOAT_NAME PIC X(17) QUERY_HEADER IS "BOAT NAME". 
03 TYPE. 
06 BUILDER PIC X(10). 
06 MODEL PIC X(10). 


MAIN PAYABLES USING PAYABLES_REC ON DTR$LIBRARY:PAYABLES . DAT; 
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ry 
. 


RECORD PAYABLES_REC USING 
O1 PAYABLE. 


O5 ORDER_NUM PIC 9(7). 

O05 TYPE. . 

10 MANUFACTURER PIC IS X(10) 
QUERY_NAME IS BUILDER 
QUERY_HEADER IS "VENDOR". 

10 MODEL PIC IS X(10) 
QUERY_HEADER IS "ITEM_TYPE" . 

O5 WHSLE_PRICE PIC 9(5) 

EDIT_STRING IS $$$,$$$. 

O05 ITEMS_RECEIVED USAGE IS DATE 
MISSING VALUE IS 010101 
EDIT_STRING IS NN/DD/YY?7"NO GOODS". 

O05 INVOICE_DUE USAGE IS DATE 
MISSING VALUE IS 010101 
EDIT_STRING IS NN/DD/YY?"NO INVCE". 

05 BILL_PAID USAGE IS DATE 
MISSING VALUE IS 010101 
EDIT_STRING IS NN/DD/YY?"NOT PAID". 

O5 AGE COMPUTED BY FN$FLOOR(("TODAY" - INVOICE_DUE) /30) 
EDIT_STRING IS Z9. 


DOMAIN PERSONNEL USING PERSONNEL_REC ON DTR$LIBRARY: PERSON. DAT; 


. 
. 


RECORD PERSONNEL_REC USING 


01 PERSON. 
05 ID PIC IS 9(5). 
O05 EMPLOYEE_STATUS Pic IS X(11) 
QUERY_NAME IS STATUS 
QUERY_HEADER IS "STATUS" 
VALID IF STATUS EQ "TRAINEE", "EXPERIENCE! 
O05 EMPLOYEE_NAME QUERY_NAME IS NAME. 
10 FIRST_NAME PIC IS X(10) 
QUERY_NAME IS F_NAME. 
10 LAST_NAME PIC IS X(10) 
QUERY_NAME IS L_NAME. 
O05 DEPT PIC IS XXX. 
O05 START_DATE USAGE IS DATE 
DEFAULT VALUE IS "TODAY". 
O5 SALARY PIC IS 9(5) 
EDIT_STRING IS $$$,$$$. 
05 SUP_ID 


. 
. 


PIC IS 9(5) 
MISSING VALUE IS 0. 


DOMAIN PETS USING PET_REC ON DTR$LIBRARY: PET .DAT; 
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SCORD PET_REC 
L FAMILY. 
03 PARENTS. 
O06 FATHER PIC X(10). 
O06 MOTHER PIC X(10). 
03 NUMBER_KIDS PIC 99 EDIT_STRING IS 29. 
03 KIDS OCCURS O TO 10 TIMES DEPENDING ON NUMBER_KIDS. 
06 EACH_KID. 
O9 KID_NAME PIC X(10) QUERY_NAME IS KID. 
09 KID_AGE PIC 99 EDIT_STRING IS Z9. 
O09 PET OCCURS 2 TIMES. 
13. PET_NAME PIC X(10). 
13 PET_AGE PIC 99. 


IBLE PRICES FROM YACHTS USING 
(PE : PRICE 

SE 0 

ID_ TABLE 


tOCEDURE PRICE_PER_POUND 
LICE/DISP ("PRICE"/"PER"/"POUND") USING $$. 99 
ID- PROCEDURE 


MAIN PROJECTS USING PROJECT_REC ON DTR$LIBRARY : PROJECT. DAT; 


‘CORD PROJECT_REC USING 
PROJECT_REC. 
03 PROJ_CODE PIC 9(3) QUERY_NAME IS CODE. 
03 PROJ_NAME PIC X(10) QUERY_NAME IS NAME. 
03 MANAGER_NUM PIC 9(5) QUERY_NAME IS NUM. 


BLE RIG_TABLE 


iLOOP" : "ONE MAST", 

ETCH" : “TWO MASTS, BIG ONE IN FRONT", 
‘AWL" =: "SIMILAR TO KETCH", 

/s" : "SAILS AND BIG MOTOR", 

SE "SOMETHING ELSE" 

iD. TABLE 
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' 
! 
DOMAIN SAILBOATS 
OF YACHTS, OWNERS BY 
01 SAILBOAT OCCURS FOR YACHTS. 
03 BOAT FROM YACHTS. 
03 SKIPPERS OCCURS FOR OWNERS WITH TYPE EQ BOAT.TYPE. 
O5 NAME FROM OWNERS. 


! 
DOMAIN SALES USING SALES_REC 
ON DTR$LIBRARY: SALES. DAT; 


! 
' 
RECORD SALES_REC USING 
01 SALESREC. 
O5 SALES_NAME PIC IS X(20). 
OS START_DATE USAGE DATE. 
O5 MONTHS_EMP COMPUTED BY ("TODAY" - START_DATE)/30 
EDIT_STRING IS 229. 


O5 AMOUNT PIC IS 9(5)V99 
; EDIT_STRING IS $$$, $$$.99. 
O5 COMM_PCT | COMPUTED BY 
CHOICE 


(MONTHS_EMP LE 6 AND AMOUNT > 5000) THEN 10 
(MONTHS_EMP LE 6) THEN 05 
(AMOUNT > 10000) THEN 12 
ELSE 07 

END_CHOICE 

EDIT_STRING IS Z9%. 

OS RATING COMPUTED BY 

CHOICE 
(MONTHS_EMP LE 6 AND AMOUNT > 5000) THEN "ABOVE 
(AMOUNT > 10000) THEN "ABOVE QUOTA" 
ELSE "BELOW QUOTA" 


END_CHOICE. 
! 
! 
PROCEDURE VERIFY 
VERIFY USING 
BEGIN 
RIG = FN$UPCASE (RIG) 
PRINT 


DISPLAY “IF RECORD IS OK, CONFIRM WITH Y" 
IF *.CONFIRM NOT CONTAINING "Y" THEN ABORT "UPDATE ABORTED" 


END 
END-PROCEDURE 
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1 


ECORD YACHT USING 


BOAT 
03 TYPE. 

O6 MANUFACTURER PIC X(10) 
QUERY_NAME IS BUILDER. 

06 MODEL PIC X(10). 

03 SPECIFICATIONS 

QUERY_NAME SPECS. 

O06 RIG PIC X(6) 

VALID IF RIG CONT "SLOOP", "KETCH", "MS", "YAWL". 

06 LENGTH_OVER_ALL PIC XXX 
VALID IF LOA BETWEEN 15 AND 50 
QUERY_NAME IS LOA. 

06 DISPLACEMENT PIC 99999 
QUERY_HEADER IS "WEIGHT" 
EDIT_STRING IS ZZ,2ZZ9 

_ ‘QUERY_NAME IS DISP. 

06 BEAM PIC 99 MISSING VALUE IS 0. 

06 PRICE PIC 99999 
MISSING VALUE IS 0 
VALID IF PRICE>DISP*1.3 OR PRICE EQ 0 
EDIT_STRING IS $$$, $$$. 


JMAIN YACHTS USING YACHT ON YACHT.DAT; 


JMAIN YACHTS_SEQUENTIAL USING YACHT ON DTR$LIBRARY: YACHT. SEQ; 


.2 DBMS Data Definitions and Procedures 


{OCEDURE BOM_LIST 
IR FIRST 5 PARTS WITH PART_STATUS = "G" 


BEGIN 
PRINT "Part :" ||] PART_ID ||| "(" ||] PART_DESC ||] ")" 
FOR CLASSES OWNER CLASS_PART 
PRINT " Class :" ||| CLASS_DESC 
PRINT " Cost :", PART_COST (-) USING $$ 
PRINT " Price :", PART_PRICE (-) USING $ 
PRINT " Bill of Materials :" 
FOR COMPONENTS MEMBER OF PART_USES 
FOR PARTS OWNER PART_USED_ON 
PRINT " Quantity : ", COMP_QUANTITY (-) USING Z2z9, 
" Part :" ||| PART_ID ||| "(" |{!] PART_DESC ||| ")" 
PRINT SKIP 


END 
D-PROCEDURE 


9.999 


$$$ ,$ 
$$$$ ,$$9.999 


PAA 


$ 
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! 
! 
DOMAIN CLASSES 
USING CLASS 
OF DATABASE PARTS_DB; 


! 
! 
DOMAIN CLASS_VIEW OF 
CLASSES, PART_S, EMPLOYEES, COMPONENTS, SUPPLIES USING 
O01 CLASS_RECORD OCCURS FOR CLASSES. 
03 CLASS_CODE FROM CLASSES. 
03 PART_GROUP OCCURS FOR PART_S MEMBER OF CLASS_PART. 
O05 PART_DESC FROM PART_S. 
O05 EMPLOYEE_GROUP OCCURS FOR EMPLOYEES OWNER RESPONSIBLE_FOR. 
07 EMP_ID FROM EMPLOYEES. 
O05 COMPONENT_GROUP OCCURS FOR COMPONENTS MEMBER OF PART_USES. 
07 COMP_SUB_PART FROM COMPONENTS. 
05 SUPPLY_GROUP OCCURS FOR SUPPLIES MEMBER OF PART_INFO. 
07 SUP_TYPE FROM SUPPLIES. 


! 
! 
DOMAIN COMPONENTS 


USING COMPONENT 
OF DATABASE PARTS_DB; 


! 
! 
DOMAIN DIVISIONS 
USING DIVISION 
OF DATABASE PARTS_DB; 


! 
! 
DOMAIN EMPLOYEES 
USING EMPLOYEE 
OF DATABASE PARTS_DB; 


i 
' 
DATABASE PARTS_DB 
USING SUBSCHEMA DTR_SUBSCHEMA 
OF SCHEMA PARTS 
ON DTR$LIBRARY : DTRPARTDB ; 


{ 
! 
DOMAIN PART_S 


USING PART 
OF DATABASE PARTS_DB; 
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tOCEDURE PRINT_NEW_DIVISION 
JR DIVISIONS WITH DIV_NAME CONTAINING "Firmware" 
PRINT ALL DIV_NAME, 
ALL COL 30, EMP_LAST_NAME ("Manager"/"_ 0 ") OF 
EMPLOYEES OWNER MANAGES, 
ALL COL 60, EMP_LAST_NAME ("Personpower"/"__ 9 ") OF 
EMPLOYEES MEMBER OF CONSISTS_OF 
ID-PROCEDURE 


JMAIN QUOTES 
JISING QUOTE 
OF DATABASE PARTS_DB; 


‘OCEDURE READY_PARTS 


‘ADY CLASSES, PART_S AS PARTS, COMPONENTS, VENDORS, SUPPLIES, QUOTES, 
IPLOYEES, DIVISIONS 
ID-PROCEDURE 


(OCEDURE READY_PARTS_WRITE 
ADY CLASSES WRITE, PART_S AS PARTS WRITE, COMPONENTS WRITE, VENDORS WRITE, 


PLIES WRITE, QUOTES WRITE, EMPLOYEES WRITE, DIVISIONS WRITE 
D-PROCEDURE 
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' 
" 
PROCEDURE RESPONSIBLE_LIST 
FOR FIRST 5 OVERSEER IN EMPLOYEES 
BEGIN 
DECLARE TEXT PICTURE X(1000). 
TEXT = EMP_FIRST_NAME ||| EMP_LAST_NAME 
IF ANY PARTS MEMBER RESPONSIBLE_FOR 
THEN BEGIN 
TEX TEXT ||| "oversees production of" 
TEXT = TEXT ||| COUNT OF PARTS MEMBER RESPONSIBLE_FOR 
TEXT = TEXT ||| "part" 
IF COUNT OF PARTS MEMBER | ten ores FOR NOT EQUAL 1 
THEN TEXT = TEXT || 
TEXT = TEXT || "." 
TEXT = TEXT ||| "He/She" 
END 
FOR DIVISIONS OWNER CONSISTS_OF 
BEGIN 
FOR MANAGER IN EMPLOYEES OWNER MANAGES 
BEGIN 
DECLARE COHORT_COUNT PICTURE 999. 
DECLARE COHORT_NUMBER PICTURE 9. 
COHORT_COUNT = 
COUNT OF EMPLOYEES MEMBER OF OVERSEER.CONSISTS_OF WITH 
EMP_ID NOT EQUAL OVERSEER.EMP_ID AND 
EMP_ID NOT EQUAL MANAGER.EMP_ID 
IF COHORT_COUNT > O 
THEN TEXT = TEXT ||| "and his/her cohort" 
IF COHORT_COUNT > 1 
THEN TEXT = TEXT || "s" 
COHORT_NUMBER = O 
FOR FIRST 3 EMPLOYEES MEMBER OF OVERSEER.CONSISTS_OF WITH 
EMP_ID NOT EQUAL OVERSEER.EMP_ID AND 
2e EMP_ID NOT EQUAL MANAGER. EMP_ID 
GIN 


COHORT_NUMBER = COHORT. NUMBER + 1 

IF COHORT_NUMBER > 1 
THEN TEXT = TEXT || "," 

IF COHORT_COUNT = COHORT_NUMBER AND COHORT_COUNT > 1 
THEN TEXT = TEXT ||] "and" 

TEXT = TEXT ||| EMP_FIRST_NAME ||| EMP_LAST_NAME 


END 
IF COHORT_COUNT > 3 
THEN TEXT = TEXT || ", and others too numerous to mentio1 
TEXT = TEXT ||| "report" 
IF COHORT_COUNT = 0 
THEN TEXT = TEXT || "s" 
TEXT TEXT ||| "to" 
TEXT TEXT ||| EMP_FIRST_NAME ||| EMP_LAST_NAME 
EET TEXT || ", manager of the" 
N 
TEXT = TEXT ||| DIV_NAME 
TEXT = TEXT ||| "division." 
END 
PRINT SKIP, TEXT (-) USING T(70) 


END 
END-PROCEDURE 


"of Wl 


B-10 Sample Database Definitions and Procedures 


\OMAIN SUPPLIES 
USING SUPPLY 
OF DATABASE PARTS_DB; 


OMAIN VENDORS 
USING VENDOR 
OF DATABASE PARTS_DB; 


3.3 Rdb Data Definitions and Procedures 


OMAIN COLLEGES 
USING COLLEGES OF DATABASE PERSONNEL; 


JMAIN DEGREES 
USING DEGREES OF DATABASE PERSONNEL; 


JMAIN DEPARTMENTS 
USING DEPARTMENTS OF DATABASE PERSONNEL; 


IMAIN DEPARTMENT_STAFF OF DEPARTMENTS, EMPLOYEES, JOB_HISTORY 
. TOP OCCURS FOR DEPARTMENTS CROSS JOB_ HISTORY OVER DEPARTMENT_CODE CROSS 

EMPLOYEES OVER EMPLOYEE_ID WITH JOB_END MISSING. 
03 DEPARTMENT_CODE FROM DEPARTMENTS. 
03 DEPARTMENT_NAME FROM DEPARTMENTS. 
03 EMPLOYEE_ID FROM EMPLOYEES. 
03 FIRST_NAME FROM EMPLOYEES. 
03 LAST_NAME FROM EMPLOYEES. 


BLE DEPARTMENT_TABLE FROM DEPARTMENTS USING 
PARTMENT_CODE : DEPARTMENT_NAME 

SE "No department". 

D_TABLE 


MAIN EMPLOYEES 
USING EMPLOYEES OF DATABASE PERSONNEL; 
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DOMAIN EMPLOYEE_EDUCATION OF eee COLLEGES, DEGREES USING 
01 TOP OCCURS FOR EMPLOYEES. 


. 
’ 


03 LAST_NAME FROM EMPLOYEES. 
03 DEG OCCURS FOR DEGREES WITH EMPLOYEE_ID EQ EMPLOYEES . EMPLOYEE. 
OS DEGREE FROM DEGREES. 
OS DEGREE_FIELD FROM DEGREES. 
O5 COLL OCCURS FOR COLLEGES WITH 
COLLEGE_CODE EQ DEGREES .COLLEGE_CODE. 
07 COLLEGE_NAME FROM COLLEGES. 


PROCEDURE EMPLOYEE_INFO 
BEGIN 
FOR FIRST 1 EMPLOYEES 


BEGIN 

PRINT NEW_PAGE, SKIP 2 

PRINT COL 30, "Employee Profile", SKIP 2 

FOR WORK_STATUS WITH STATUS_CODE EQ EMPLOYEES .STATUS_CODE 


‘PRINT "Id:", COL 15, EMPLOYEE_ID(-) USING X(10), 


COL 50, STATUS_NAME| | |STATUS_TYPE, SKIP 


PRINT "Name:", COL 15, FIRST_NAME| | |MIDDLE_INITIAL||"."| | |LAST_NAME 
IF ADDRESS DATA NE " " THEN 
BEGIN 
PRINT "Address: ", COL 15, ADDRESS_DATA(-), 
COL 15, STREET(-) 
END ELSE PRINT "Address: ", COL 15, STREET(-) 
PRINT COL 15, TOWN||","||{STATE| |" "| ZIP 


PRINT SKIP, "Job History: . 
FOR JOB_HISTORY WITH 
EMPLOYEE_ID EQ EMPLOYEES .EMPLOYEE_ID SORTED BY 
DESCENDING JOB_START 
BEGIN 
FOR JOBS WITH JOB_CODE EQ JOB_HISTORY.JOB_CODE 
BEGIN - 
PRINT (DEPARTMENT_CODE VIA DEPARTMENT_TABLE) ("DEPT") USING | 
JOB_TITLE, 
WAGE_CLASS, 
MINIMUM_SALARY USING $$$, $$$, 
MAXIMUM_SALARY USING $$$, $$$, 
JOB_START USING NN/DD/YY, 
JOB_END USING NN/DD/YY 
END 
END 


SKIP, "Salary History:" 
FOR SALARY_HISTORY WITH EMPLOYEE_ID EQ EMPLOYEES. EMPLOYEE_ID SORTED 
DESCENDING SALARY_START 
PRINT SALARY_START USING NN/DD/YY, 
SALARY_END USING NN/DD/YY, 
SALARY_AMOUNT USING $$$, $$$ 
IF ANY DEGREES WITH EMPLOYEE_ID EQ EMPLOYEES.EMPLOYEE_ID THEN c 
PRIN reas PSS ee Se eae eee eee eo Sea ese See ee eae ease , 
SKIP, "Education:", SKIP 


(continued on next page) 
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FOR DEGREES WITH EMPLOYEE_ID = EMPLOYEES .EMPLOYEE_ID 
FOR COLLEGES WITH COLLEGE_CODE = DEGREES . COLLEGE_CODE 


BEGIN 
PRINT COLLEGE_NAME, YEAR_GIVEN, DEGREE, 
DEGREE_FIELD 


PRINT NEW_PAGE 
D : 
D-PROCEDURE 


MAIN JOBS 
USING JOBS OF DATABASE PERSONNEL; 


MAIN JOB_HISTORY 
USING JOB_HISTORY OF DATABASE PERSONNEL; 


BLE NAME_TABLE FROM EMPLOYEES USING 
PLOYEE_ID : LAST_NAME 

SE a of ; 

D_ TABLE 


OCEDURE READY_PERSONNEL 
ADY COLLEGES SHARED READ, DEGREES SHARED READ, - 


DEPARTMENTS SHARED READ, EMPLOYEES SHARED READ, 


JOBS SHARED READ, JOB_HISTORY SHARED READ, - 


SALARY_HISTORY SHARED READ, WORK_STATUS SHARED READ 


)-PROCEDURE 


JCEDURE READY_PERSONNEL_WRITE 


ADY COLLEGES WRITE, DEGREES WRITE, ‘DEPARTMENTS WRITE, - 


EMPLOYEES WRITE, JOBS WRITE, JOB_ HISTORY WRITE, - 


SALARY_HISTORY WRITE, WORK_STATUS WRITE 
)- PROCEDURE 


MAIN SALARY_HISTORY 
USING SALARY_HISTORY OF DATABASE PERSONNEL; 
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t 

PROCEDURE SALARY_REPORT 

FIND FIRST 3 EMPLOYEES 

FIND CURRENT CROSS SALARY_HISTORY OVER EMPLOYEE_ID 

FIND CURRENT CROSS JOB_HISTORY OVER EMPLOYEE_ID WITH 
JOB_START EQ SALARY_HISTORY.SALARY_START 

FIND CURRENT CROSS JOBS WITH JOB_CODE EQ JOB_HISTORY.JOB_CODE 

REPORT CURRENT SORTED. BY LAST_NAME, SALARY_AMOUNT 

AT TOP OF EMPLOYEE_ID PRINT SKIP, COL 1, 
EMPLOYEE_ID| | |FIRST_NAME|||LAST_NAME, SKIP 2 

PRINT COL 1, JOB_START USING NN/DD/YY, JOB_TITLE, 
MINIMUM_SALARY, SALARY_AMOUNT ,MAXIMUM_SALARY 


END_REPORT 
END-PROCEDURE 


! 
! 
DOMAIN WORK_STATUS 
USING WORK_STATUS OF DATABASE PERSONNEL; 
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disadvantages of. 12-17 
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in procedures, 7-5 
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Common Data Dictionary, 1-4 
Compound Booleans 
evaluation, 12-23 
Compound statements 
using procedures in, 7-12 
COMPUTED BY field, 11-11 to 11-14 
Conditional value expressions 
IF-THEN-ELSE, 11-13 
CONNECT statement, 14-41 
CONTAINING relational operator 
optimizing queries with, 12-15 
Context block, A-2 
How DATATRIEVE searches 
through a context block, A-4 
how DATATRIEVE searches 
through a context block, A-2 
name recognition on the “last-in 
first-out” basis, A-5 
Context errors 
avoiding context errors, A-9 to 
A-14 
avoiding with FIND and SELECT, 
6-12 
Context Searcher, 6-20 
activating with the SET SEARCH 
command, 1-13 
Context variables, 9-6 to 9-9, A-9 
example, A-12 
Context, single record, A-17 
Continuation character (-), 1-11 
Controlling output, 1-10 
COPY command (DCL), 1-9 
CROSS clause, 2-2, 2-14, 2-18 
combining two domains with, 2-15 
defining views with, 5-6 
flattening hierarchies with, 6-21 
optimizing queries with, 12-17 to 
12-21 
using with DBMS databases, 14-30 
CURRENCY clause 
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using with DBMS databases, 14-3! 


D 


Data 
accessing Rdb, 15-4 
combining from two or more 
domains, 10-5 
modifying, 4-2 
modifying using FOR statement, 
4-9 
segmented string field data type, 
15-19 
transfer between domains, 10-4 
Data Manipulation Facility (DDMF), 
16-2 
Database 
See DBMS databases 
See Rdb databases 
DATATRIEVE 
exiting, 1-2 
invoking, 1-1 to 1-2 
Date arithmetic, 11-12 
Date value expressions, 11-12 
Dates 
formatting, 1-15 
DBMS databases, 1-3 
accessing information through set 
14-20 
accessing using DTR domain defi- 
nitions, 14-8 
accessing with READY database 
command, 14-6 
combining the MEMBER and 
OWNER clauses, 14-27 
connecting members of sets, 14-4( 
connecting records to sets, 14-37 
defining a database instance, 14-5 
defining domains. 14-9 
disconnecting members of sets, 
14-44 
finding data from multiple domair 
14-27 
forming collections, 14-16 


forming collections of set data, 
14-21 

forming record streams, 14-18 

forming record streams of DBMS 
set data, 14-22 

forming simple queries, 14-14 

modifying a single record, 14-35 

queries for set information, 14-19 

readying domains, 14-10 

readying individual records, 14-8 


RECON ECT statement example, 


14-450 

reconnecting members of sets, 
14-44... 

record membership table, 14-48t 

record occurrence, 14-4 

record removal characteristics, 
(14-4205. 

results of readying domains, 14-10 

rse clause format, 14-15 

rse clause in: simple queries, 14-14 

sample procedures using domains, 
14-33. - . 

set occurrence, 14-4 

sets with automatic insertion char- 
acteristic, 14-38 

sets with manual insertion, 14-40 

sets with optional members, 14-46 

STORE statement with 
CURRENCY clause, 14-40 

storing records, 14-37 

system-owned sets, 14-38 

using CONNECT statement, 14-41 

using CURRENCY clause to pro- 
vide context, 14-38 

using flat views, 14-32 

using hierarchical views, 14-31 

using SHOW EIBEDS command, 
14-12 4 

using SHOW SETS command, 
14-13 

using the COMMIT statement, 
14-49 

using the CROSS clause, 14-30 


using the DEFINE DATABASE 
command, 14-5 
using the DEFINE DOMAIN com- 
mand, 14-9 
using the ERASE statement, 14- 42 
using the EXIT command, 14-49 
using the FIND statement, 14-16 
using the FIND statement and 
WITHIN clause, 14-21 | 
using the FINISH command, 14-49 
using the MEMBER clause in the 
FIND statement, 14-24 
using the OWNER clause in the 
FIND statement, 14-25 
using the PRINT CURRENT state- 
ment, 14-17 | 
using the PRINT statement, 14- 17 
using the ROLLBACK statement, 
14-49 
using the SELECT statement, 
14-17 
using the SET SEARCH com- 
mand, 14-25 
using view domains, 14-31 
DDMF 
See Data Manipulation Facility 
(DDMF) 
DECLARE 
Variable-name, 9-1 
DECnet account 
using the default account, 16-6 
DEFINE DATABASE command 
format, 14-5 
Rdb databases, 15-3 
DEFINE DOMAIN command, 1-3 
DBMS, 14-8 
Rdb relations, 15-9 
DEFINE PROCEDURE command, 
1-6, 7-2 
DEFINE TABLE command, 1-7 
Defining 
dynamic hierarchies, 6-41 
hierarchies, 6-36 
procedures, 7-1 
records, 11-1 to 11-14 
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Dictionaries 
compared to VAX/VMS directories, 
1-4 
DISPLAY FORM statement, 13-5 
handling numeric data, 13-25 
storing hierarchical records with, 
13-21 
using to modify hierarchical 
records, 13-24 
Distributed data, 1-7 
Distributed DATATRIEVE applica- 
tions, 16-5 to 16-7 
Domains 
See also DEFINE DOMAIN 
command 
combining data from multiple, 10-5 
defining for a DBMS database, 
14-9 
description of, 1-3 
distributed, 16-1 
network 
accessing, 16-5 to 16-7 
defining, 16-2 to 16-5 
remote, 16-1 
restructuring, 10-1, 10-2 
transfer data between, 10-4 
using forms with, 13-3 
view, 1-6, 6-37 
See also View domains 
Dynamic hierarchies, 6-41 


E 
Editing 
command files, 8-3 ’ 
procedures, 7-5 
EQUAL relational operator 
optimizing queries with, 12-15 
Errors 
See also Context errors 
avoiding when using the MODIFY 
statement, 4-12 
EXIT command 
using with DBMS databases, 14-49 
using with Rdb databases, 15-14 
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F 


FDL 
See File Definition Language (FDI 
Fields 
adding to record definition, 10-3 
assigning values using MODIFY, 
4-12 
assigning values with STORE 
statement, 3-1 
File Definition Language (FDL) 
choosing bucket size, 12-5 
choosing index depth, 12-8 
creating the data file, 12-9 
plotting bucket size, 12-7 
using, 12-5 
using CONVERT/FDL, 12-15 
File optimization 
assigning global buffers, 12-14 
choosing bucket size, 12-5 
choosing index depth, 12-8 
default characteristics of 
DATATRIEVE files, 12-5 
determining fill factor, 12-15 
determining global buffers, 12-9 
maintaining good performance, 
12-14 
minimizing fragmentation, 12-5 
moving data from old file to new 
file, 12-15 
using FDL, 12-5 
Files 
changing organization of, 10-8, 
12-1, 12-3 
defining, 12-5 
defining indexed, 12-1 
defining using FDL, 12-3 to 12-15 
maintaining using FDL, 12-14 
optimization, 12-1 to 12-15 
organization 
selecting, 12-1 
sequential vs. indexed, 12-1 
using indexed, 12-1 
using sequential, 12-1 
FIND statement 


advantages of, 1-7 
disadvantages of, 12-17 
establishing context for a list with, 
6-12 
performance issues, 12-18 
using to modify records in repeat- 
ing fields, 6-29 
using to retrieve records in repeat- 
ing fields, 6-12 
using with DBMS records, 14-16 
INISH command 
using with DBMS databases, 14-49 
using with Rdb databases, 15-11 
N$HOUR, 1-18 
N$SINIT TIMER, 12-21 
N$JULIAN, 11-13 
N$SHOW TIMER, 12-21 
N$WIDTH, 1-11 
OR statement 
creating hierarchies with, 6-41 
flattening hierarchies with, 6-27 
modifying data, 4-9 
modifying list items with, 6-32 
retrieving list items with, 6-14 
orm field names 
displaying, 13-6 
ORM IS clause, 13-3, 13-28 
ORMAT value expression, 13-25, 
13-26 
orms, 13-1 
converting from FMS to TDMS, 
13-7, 13-15 
defining, 13-7, 13-10 
DISPLAY FORM statement, 13-5 
displaying data on, 13-16 
displaying field names in, 13-6 
domains and, 13-3 
enabling and disabling use of, 13-16 
GET FORM value expression, 
13-19 
libraries, 13-14 
PUT FORM assignment state- 
ment, 13-17 


storing and modifying data with, 
13-18 
Functions 
FN$HOUR, 1-17 
FN$INIT TIMER, 12-21 
FN$SHOW TIMER, 12-21 


G 
GET FORM value expression, 13-19 


H 


Hierarchies, 6-10 
creating with FOR statements, 
6-41 
creating with inner print lists, 6-39 
creating with view domains, 6-37 
dynamic, 6-41 
flattening, 6-21, 11-1 to 11-5 
Hyphen (-) 
using as a continuation character, 
1-11 


Indexed files 
choosing primary and alternate 
keys, 12-2 
default parameters, 12-4 
optimization, 12-1 to 12-15 
using, 12-1 
versus sequential files, 12-1 
Invoking 
See @ (Invoke Command File) 
command 
procedures, 7-2 


K 


Key optimization, 12-2 
summary, 12-24 


L 


List fields 
See Lists or Repeating Fields 
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Lists 
defining, 6-3 
modifying values in, 6-29 
retrieving values from, 6-10 
Logical names 
DTR$SDATE INPUT, 1-15 
DTRSSTARTUP, 1-17 
SYS$CURRENCY, 1-16 
SYS$DIGIT SEP, 1-16 
SYS$RADIX POINT, 1-16 
Login command files 
effect on remote access, 16-7 


Maintaining 
command files, 8-10 
procedures, 7-15 
MATCH, 13-21 
MODIFY statement 
ALL option, 4-7 
assigning field values with, 4-12 
avoiding errors, 4-12 
examples, 4-3 
including the rse, 4-11 
modifying repeating fields with, 
6-29 
Rdb data, 15-31 
USING clause with assignment- 
statement, 4-6 
using prompting expressions in, 
4-12 
VERIFY clause, 4-17 
with VERIFY clause, 4-6 
Modifying data 
in repeating fields, 6-29 
restrictions, 13-28 


N 


Name recognition, A-5 
Nested FOR loops 
optimization, 12-17 to 12-21 
Nesting 
procedures, 7-10 
Network domains 
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accessing, 16-5 to 16-7 
defining, 16-2 to 16-5. 
NOT Boolean operator, 2-13 


O 


OCCURS clause, 6-6, 11-2 
OCCURS...DEPENDING clause, 6-7 
Optimization 
See also file optimization 
summary, 12-24 


P 


Performance 
checking with DTR timing func- 
tions, 12-22 
choosing optimal queries, 12-15 to 
12-22 
compound Boolean considerations, 
12-23 
file organization considerations, 
12-1 
optimizing file parameters, 12-5 
optimizing for Rdb, 15-32 
PRINT statement 
using with DBMS databases, 14-17 
Procedures, 7-1 
aborting, 7-7 
arguments and clauses in, 7-4 
commands and statements in, 7-3 
comments in, 7-5 
contents of, 7-3 
defining, 7-1 
_ deleting, 7-16 
description of, 1-6 
editing, 7-5 
examples of, 7-8 
generalizing, 7-13 
invoking, 7-2 
maintaining, 7-15 
~ nesting, 7-10 
protection, 7-16 
timing to improve efficiency, 12-21 
using in compound statements, 
7-12 


using to trap errors, 7-6 

ompting expressions 

in MODIFY statement, 4-12 

in STORE statement, 3-4 

ompting value expressions, 9-6 

‘ompts 

using for input prompting, 4-15 

using in STORE statements, 3-2 

JT FORM assignment statement, 
13-17 


ialified field names, A-10 
iarterly summaries, 11-12 to 11-14 


ib databases, 1-3 

COMMIT statement, 15-13 

creating a path name, 15-3 

default access mode, 15-8 

DEFINE DATABASE command, 
15-3 

DEFINE DOMAIN command, 15-9 

defining view domains, 15-10 

examples of readying, 15-8 

optimizing performance, 15-32 

readying, 15-8 

readying some relations, L5- 8 

relations, 15-1 

ROLLBACK statement, 15-13 

segmented string data type 

See Segmented string fields 

storing data in an Rdb database, 
15-11 

using COMMIT statement, 15-14 

using DATATRIEVE to access Rdb 
data, 15-3 

using EXIT command, 15-14 

using FINISH command, 15-11, 
15-14 

using ROLLBACK statement, 
15-16 

using SHOW PETS command, 
15- 11 


using SHOW READY command, 
15-10 
using view relations, 15-8 
using views, 15-8 
validating data in, 15-32 
READY command 
DBMS 
format, 14-7 
USING clause, 14-8 
DBMS databases, 14-10 
Rdb databases, 15-4 
RECONNECT statement 
using with DBMS databases, 14-45 
Record definitions, 11-1 to 11-14 
adding fields, 10-3 
changing, 10-1 
flat vs. hierarchical records, 11-1 to 
11-5 
large vs. small records, 11-6 to 
11-8 
Record selection expressions, 2-1 
creating hierarchies with, 6-36 to 
6-42 
CROSS clause, 11-4 
REDUCED TO clause, 11-7 
using to form simple DBMS que- 
ries, 14-14 
Record streams 
creating hierarchies from, 6-36 to 
6-42 
. finding correct values in, 2-19 
joining records in, 2-14 
sorting by field values, 2-21 
‘specifying records in, 2-3. 
Record subsets 
creating, 10-5 
Relations 
defining domains for, 15-9 
RELEASE command 
to remove forms from workspace, | 
13-16 
Remote data, 1-7 
Remote DATATRIEVE applications, 
16-5 to 16-7 
Remote domains, 16-1 
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accessing. 16-5 to 16-7 
Repeating fields 

defining, 6-3 

modifying values in, 6-29 

retrieving values from, 6-10 
Restructuring domains, 10-1, 10-2 

adding fields, 10-3 

creating record subsets, 10-5 

example, 10-2 

to combine data, 10-5 

using aliases, 10-2, 10-6 

with Restructure statement, 11-4, 

11-8 

with STORE USING, 11-7, 11-11 
ROLLBACK statement 

DBMS databases, 14-49 

Rdb databases, 15-13 
RSE 

See Record selection expressions 
RUNNING COUNT statistical opera- 

tor, 11-7 
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Segmented string fields, 15-19 
defining, 15-20 
displaying in DATATRIEVE, 15-21 
restrictions, 15-28 
storing and modifying in 
DATATRIEVE, 15-22 
storing and modifying with a proce- 
dure, 15-24 
SELECT statement 
identifying a particular record with, 
6-12 
using to modify records in repeat- 
ing fields, 6-29 
using to retrieve records in repeat- 
ing fields, 6-12 
using with DBMS databases, 14-17 
Sequential files 
using, 12-1 
versus indexed files, 12-1 
SET ABORT command, 1-12 
SET COLUMNS PAGE command, 
1-10, 1-11 © 
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SET commands, 1-10 
SET FORM command, 1-13, 13-16 
SET PROMPT command, 1-12 
SET SEARCH command, 1-13 
using to access DBMS sets, 14-25 
using with RMS domains, 6-20 
SET SEMICOLON command, 1-14 
SET TERMINAL command, 1-11 
SET VERIFY command, 1-13 
Sets 
accessing information, 14-20 
automatic insertion characteristic, 
14-38 
combining the MEMBER and 
OWNER clauses to access 
data, 14-27 
connecting members, 14-46 
connecting records, 14-37 
disconnecting members, 14-44 
forming record streams, 14-22 
manual insertion characteristic, 
14-40 . 
occurrence, 14-4 
optional members, 14-46 
RECONNECT statement example 
14-45 
reconnecting members, 14-44 
record membership table, 14-48t 
record removal characteristics, 
14-42 
system-owned, 14-38 
using CONNECT statement, 14-4: 
using CURRENCY clause to estat 
lish context, 14-40 
using SHOW SETS command, 
14-13 
using the ERASE statement, 14-4 
using the MEMBER clause, 14-23 
using the OWNER clause, 14-23 
using the SET SEARCH comman 
for access, 14-25 
SHOW FIELDS command 
using with Rdb databases, 15-11 
SHOW FORMS command, 13-16 
SHOW READY command 
using for Rdb databases, 15-10 


}HOW SET UP command, 1-10, 
13-16 
single record context, A-17 
sorting 
field values in record streams, 2-21 
ITARTING WITH relational operator 
optimizing queries with, 12-16 
itartup command file 
using, 1-14 
TORE statement 
assigning field values with, 3-1 
direct assignments in, 3-2 
prompts, 3-2, 3-4 
USING clause, 11-7 . 
using with Rdb databases, 15-11 
using with the currency clause, 
14-38 
'UM statement, 11-14 


‘ables, 11-10 to 11-11 

See also DEFINE TABLE 

command 

description of, 1-7 

dictionary, 11-11, 11-13 
‘erminology 

DATATRIEVE, 1-3 
TODAY” value expression, 11-12 


} 
ISING clause 


in STORE statement, 3-2 
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Variables, 9-1 to 9-6 
changing the value of, 9-6 
context, A-9 
declaring, 9-1 to 9-2 
global, 9-2, 9-3 to 9-4 
local, 9-2, 9-3 
to assign values to fields, 9-4 to 9-5 
VERIFY clause 
MODIFY statement, 4-17 
View domains, 1-6, 6-37 
See also DEFINE DOMAIN 
command 
defining for Rdb, 15-10 
restriction for modifying records, 
13-28 
using lists in, 6-37 
using more than one domain, 5-5 
using subsets of fields, 5-4 
using subsets of records, 5-2 
using with DBMS databases, 14-31 
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WITH clause 
using to restrict lists, 2-5 
WITHIN clause 
using in the FIND statement for 
DBMS sets, 14-21 


Index-9 


HOW TO ORDER ADDITIONAL DOCUMENTATION 


DIRECT TELEPHONE ORDERS 


In Continental USA In Canada In New Hampshire, 
and Puerto Rico call 800-267-6146 Alaska or Hawaii 
call 800-258-1710 call 603-884-6660 


DIRECT MAIL ORDERS (U.S. and Puerto Rico*) 


DIGITAL EQUIPMENT CORPORATION . 
P.O. Box CS2008 
Nashua, New Hampshire 03061 


DIRECT MAIL ORDERS (Canada) 


DIGITAL EQUIPMENT OF CANADA LTD. 
940 Belfast Road 
Ottawa, Ontario, Canada K1G 4C2 
Attn: P&SG Business Manager 


INTERNATIONAL 


DIGITAL EQUIPMENT CORPORATION 
P&SG Business Manager 
c/o Digital's local subsidiary 
or approved distributor 


Internal orders should be placed through the Software Distribution Center (SDC), Digital 
Equipment Corporation, Northboro, Massachusetts 01532 


*Any prepaid order from Puerto Rico must be placed 
with the Local Digital Subsidiary: 
809-754-7575 


VAX DATATRIEVE 
User’s Guide 
AA-KO80D-TE 


Reader’s Comments 


Note: This form is for document comments only. DIGITAL will use comments submitted on this 
form at the company’s discretion. If you require a written reply and are eligible to receive 
one under Software Performance Report (SPR) service, submit your comments on an SPR 
form. 


Did you find this manyal understandable, usable, and well-organized? Please make suggestions 
for improvement. 
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